# Démarrage avec l’API

Appelez directement les API Google Search et YouTube en HTTP. Envoyez une requête et lisez la réponse JSON, sans SDK.

Référence canonique : https://flashdata.dev/fr/docs/guides/http-quickstart
Vérifié le 2026-11-04 par FlashData

<a id="application"></a>

## Effectuez votre première requête HTTP

Définissez votre clé API, lancez une recherche Google et examinez la réponse enregistrée.


<a id="prepare"></a>

### Authentifiez-vous

Créez un compte, vérifiez votre adresse e-mail et créez une clé autorisant Google Search. Vous pouvez réutiliser une clé existante.

Exécutez cette commande dans votre terminal et collez la clé dans la saisie masquée. Ignorez cette étape si FLASHDATA_API_KEY est déjà définie.

#### Bash

##### Définir votre clé

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```


#### PowerShell 7

##### Définir votre clé

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```


- [Créer un compte](https://flashdata.dev/signup)
- [Ouvrir les clés API](https://flashdata.dev/app/api-keys)
- [Authentification des agents](https://flashdata.dev/auth.md)

<a id="curl"></a>

### Lancez une recherche

Choisissez un client et exécutez l’exemple dans le même terminal. Chaque exemple envoie une requête POST à https://data.flashdata.dev/v1/queries/realtime et affiche la réponse JSON. Utilisez X-API-Key pour l’authentification et Content-Type: application/json pour envoyer du JSON.

#### cURL

cURL 7.76+ · Bash sous Linux, macOS ou Git Bash. Collez la commande et exécutez-la.

##### Recherche · Bash / cURL

```bash
curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST https://data.flashdata.dev/v1/queries/realtime \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}'
```


#### PowerShell 7

PowerShell 7+ · Collez cette commande PowerShell native.

##### Recherche · PowerShell

```powershell
$flashdataRequest = '{"source":"google_search","query":"battery recycling research","params":{"num":5}}'
$flashdataSearch = @{
  Uri = 'https://data.flashdata.dev/v1/queries/realtime'
  Method = 'Post'
  Headers = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
  ContentType = 'application/json'
  Body = $flashdataRequest
  TimeoutSec = 70
  MaximumRedirection = 0
  SkipHttpErrorCheck = $true
  ErrorAction = 'Stop'
}
$flashdataResponse = Invoke-WebRequest @flashdataSearch
$flashdataResponse.Content
if ($flashdataResponse.StatusCode -ge 400) {
  throw "HTTP $($flashdataResponse.StatusCode). Inspect the response above before retrying."
}
```


#### JavaScript

Node.js 22+ · Enregistrez le code dans search.mjs, puis exécutez-le localement ou sur votre serveur. Il utilise la fonction fetch intégrée ; aucune installation npm n’est nécessaire.

##### search.mjs

```javascript
const key = process.env.FLASHDATA_API_KEY;
if (!key) throw new Error("Set FLASHDATA_API_KEY in this terminal.");

let response;
try {
  response = await fetch("https://data.flashdata.dev/v1/queries/realtime", {
    method: "POST",
    redirect: "error",
    signal: AbortSignal.timeout(70000),
    headers: { "X-API-Key": key, "Content-Type": "application/json" },
    body: JSON.stringify({"source":"google_search","query":"battery recycling research","params":{"num":5}}),
  });
} catch {
  throw new Error("Request did not complete. Check History before resubmitting.");
}

const body = await response.text();
console.log(body); // Print the full response before checking its status.
if (!response.ok) {
  const retryAfter = response.headers.get("retry-after");
  throw new Error("HTTP " + response.status + ". See the response above." +
    (retryAfter ? " Retry-After: " + retryAfter : ""));
}
let result;
try {
  result = JSON.parse(body);
} catch {
  throw new Error("Expected JSON. Inspect the response above and the API URL.");
}
if (!result || result.error === true || result.status !== "done" || !Array.isArray(result.results)) {
  throw new Error("Query did not succeed. Inspect status and error in the response above.");
}
```

##### Exécuter · JavaScript

```bash
node search.mjs
```


#### Python

Python 3.10+ · Enregistrez le code dans search.py. Il utilise uniquement la bibliothèque standard, sans installation pip. Utilisez python3 ou py -3 si c’est la commande Python de votre système.

##### search.py

```python
import json
import os
import urllib.error
import urllib.request

key = os.environ.get("FLASHDATA_API_KEY")
if not key:
    raise SystemExit("Set FLASHDATA_API_KEY in this terminal.")

# Do not forward the API key to a redirect destination.
class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://data.flashdata.dev/v1/queries/realtime",
    data=json.dumps({"source":"google_search","query":"battery recycling research","params":{"num":5}}).encode("utf-8"),
    headers={"X-API-Key": key, "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.build_opener(NoRedirect).open(request, timeout=70) as response:
        body = response.read().decode("utf-8")
except urllib.error.HTTPError as error:
    print(error.read().decode("utf-8", errors="replace"))
    retry_after = error.headers.get("Retry-After")
    raise SystemExit("HTTP " + str(error.code) + ". See the response above." +
                     (" Retry-After: " + retry_after if retry_after else ""))
except (urllib.error.URLError, TimeoutError):
    raise SystemExit("Request did not complete. Check History before resubmitting.")

print(body)  # The run command saves this full response to result.json.
try:
    result = json.loads(body)
except json.JSONDecodeError:
    raise SystemExit("Expected JSON. Inspect the response above and the API URL.")
if (not isinstance(result, dict) or result.get("error") is True
        or result.get("status") != "done" or not isinstance(result.get("results"), list)):
    raise SystemExit("Query did not succeed. Inspect status and error in the response above.")
```

##### Exécuter · Python

```bash
python -X utf8 search.py
```



<a id="result"></a>

### Vérifiez le résultat

Vérifiez la réussite HTTP et status: done. Lisez les titres, liens et extraits des sources dans results[].organic, et les crédits facturés dans usage.credits.

Une liste results ou organic vide avec status: done constitue un résultat vide valide.

| Champ | Utilisation |
| --- | --- |
| status | "done" confirme que la requête s’est terminée avec succès. |
| results[0].organic[] | Résultats de recherche. Vérifiez que results n’est pas vide avant d’accéder à un élément par son index. |
| title / link / snippet | Titre, URL et extrait de la source. |
| usage.credits | Crédits réellement facturés pour cette requête. |

#### Exemple de réponse

```json
{
  "source": "google_search",
  "status": "done",
  "results": [
    {
      "organic": [
        {
          "title": "Battery recycling research",
          "link": "https://example.org/recycling",
          "snippet": "An example search excerpt."
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.02
  }
}
```


<a id="diagnostics"></a>

## Enregistrer une réponse pour le débogage

Pour enregistrer la prochaine requête que vous comptez effectuer, ajoutez ces options à la commande cURL ci-dessus. Examinez les fichiers avant de décider de retenter une requête en échec.

### cURL

```bash
--dump-header response-headers.txt --output result.json
```

- [Erreurs HTTP et récupération](https://flashdata.dev/fr/docs/errors/reference.md)

<a id="check"></a>

## Vérifier l’accès et les crédits

Ces requêtes GET lisent l’identité, le solde et les tarifs sans consommer de crédits de requête. Vérifiez le code HTTP 200 et les champs ci-dessous avant de soumettre une tâche facturable.

Lecture du compte : https://api.flashdata.dev/v2. Requêtes de données : https://data.flashdata.dev/v1. Les deux utilisent X-API-Key ; les requêtes POST en JSON utilisent aussi Content-Type: application/json.

| Lecture | Éléments à vérifier dans la réponse |
| --- | --- |
| identity | Vérifiez le compte accountId attendu, access: "ready", la présence de "google_search" dans scopes et la date expiresAt éventuelle. accountType vaut "owned" pour une clé du compte propriétaire ou "temporary" pour une clé d’essai. |
| balance | Lisez availableCredits. Toutes les clés de ce compte utilisent le même solde. |
| pricing | Dans prices[0], vérifiez que source vaut google_search et que available vaut true. Comparez estimatedCredits pour requestCount: 1 avec availableCredits. Les tarifs et le solde peuvent changer avant la soumission. |

### Bash / cURL

#### Vérifications gratuites · Bash

```bash
(
for endpoint in 'identity' 'balance' 'pricing?source=google_search&request_count=1'; do
  printf '\n%s\n' "$endpoint"
  curl --fail-with-body --silent --show-error --max-time 20 \
    --header "X-API-Key: $FLASHDATA_API_KEY" \
    --write-out '\nHTTP %{http_code}\n' \
    "https://api.flashdata.dev/v2/api-access/$endpoint" || exit
done
)
```


### PowerShell 7

#### Vérifications gratuites · PowerShell

```powershell
try {
  foreach ($flashdataPath in @('identity', 'balance', 'pricing?source=google_search&request_count=1')) {
    Write-Host $flashdataPath
    $flashdataRead = @{
      Uri = "https://api.flashdata.dev/v2/api-access/$flashdataPath"
      Headers = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
      TimeoutSec = 20
      MaximumRedirection = 0
      ErrorAction = 'Stop'
    }
    Invoke-RestMethod @flashdataRead | ConvertTo-Json -Depth 20
  }
} catch {
  throw
}
```



<a id="next"></a>

## Étapes suivantes

- [Bonnes pratiques : Google Search](https://flashdata.dev/fr/docs/guides/google-search-guide/reference.md)
- [Données YouTube](https://flashdata.dev/fr/docs/guides/youtube-data-guide/reference.md)
- [Téléchargement YouTube](https://flashdata.dev/fr/docs/guides/youtube-download-guide/reference.md)
- [Référence API](https://flashdata.dev/fr/docs/api-reference/reference.md)
- [Spécification OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="troubleshooting"></a>

## Si une étape échoue

Lisez la réponse affichée dans le terminal. Les exemples JavaScript et Python écrivent les erreurs HTTP et Retry-After sur stderr. Chaque exemple soumet une seule requête, sans nouvelle tentative automatique.

| Symptôme | Action suivante |
| --- | --- |
| Commande introuvable ou option non prise en charge | Vérifiez la version requise par l’exemple choisi. Utilisez PowerShell 7 plutôt que Windows PowerShell 5.1, ou Bash avec cURL 7.76+. JavaScript nécessite Node 22+ et Python nécessite la version 3.10+. Installez l’environnement manquant depuis sa page officielle, rouvrez le terminal et définissez à nouveau la clé. |
| Clé manquante / 401 | Définissez FLASHDATA_API_KEY dans ce processus, puis vérifiez à nouveau l’identité. Fournissez la clé API active complète, sans préfixe Bearer. Si elle a expiré ou a été révoquée, utilisez un identifiant actuellement autorisé ; ne le collez pas dans la conversation. |
| 403 | Vérifiez la présence de google_search dans identity.scopes et la valeur ready dans access. Demandez au propriétaire la permission manquante ; modifier la source dans la requête n’accorde aucun accès. |
| 402 | Relisez le solde et comparez-le au tarif actuel. Le propriétaire peut consulter la facturation. Si l’essai est épuisé, rattachez la connexion à un compte propriétaire ; créer un autre essai ne permet pas de récupérer cet accès. |
| 400 / 422 | Lisez le message d’erreur renvoyé. Vérifiez l’hôte de données exact, la méthode POST, Content-Type et les noms des champs JSON. Utilisez des guillemets droits et une valeur numérique pour params.num, puis corrigez la requête rejetée. |
| 429 | Respectez Retry-After s’il est présent ; sinon, espacez progressivement les tentatives avec une limite et réduisez les requêtes simultanées. Ne multipliez pas les appels, les clés ou les essais pour contourner la limite. |
| HTTP 200 avec un état d’échec ou une erreur | Lisez l’erreur dans le corps de la réponse et conservez tout identifiant de requête ou de tâche. Un corps JSON correctement analysé ne prouve pas la réussite de la tâche et ne justifie pas une nouvelle soumission automatique. |
| Résultats vides | Si status vaut done, l’authentification a fonctionné. Conservez le résultat vide ou essayez une recherche plus large, qui constituera une nouvelle requête facturable. |
| Délai dépassé, connexion perdue, erreur 5xx ou HTML au lieu de JSON | Un POST peut avoir été accepté même si sa réponse a été perdue. Recherchez la requête d’origine dans l’historique et conservez les identifiants renvoyés avant de décider de la soumettre à nouveau. Les vérifications GET gratuites peuvent être retentées. Vérifiez que l’URL utilise data.flashdata.dev, et non l’hôte du site web ; ne désactivez pas la vérification TLS. |

- [Historique des requêtes](https://flashdata.dev/app/jobs)
- [Gérer les clés](https://flashdata.dev/app/api-keys)
- [Télécharger cURL](https://curl.se/download.html)
- [Installer PowerShell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell)
- [Télécharger Node.js](https://nodejs.org/en/download)
- [Télécharger Python](https://www.python.org/downloads/)
