Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Référence API

API Google Images

Obtenir une clé API

Recherchez dans Google Images et récupérez les URL des images d’origine, les vignettes, les dimensions et les pages sources au format JSON.

Préparer une requête

Paramètres avancés

Démarre à 1. Chaque page est une requête séparée.

Expression Google tbs. Les filtres pris en charge varient selon le type de recherche.

POSThttps://data.flashdata.dev/v1/queries/realtime
Python 3 · requests
python3 -m pip install requests
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "google_images",
    "query": "tokyo skyline",
    "params": {
        "gl": "us",
        "hl": "en",
        "num": 50,
        "page": 1,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key, "Accept": "application/json"},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
Résultats dans la réponse HTTPAuthentification X-API-Key

Paramètres

Envoyez source et query à la racine de l’objet JSON. Placez les options de la source dans params. Vous pouvez omettre les champs facultatifs.

Corps de la requête

sourcestring / Obligatoire
Définissez ce champ sur google_images.
querystring / Obligatoire
Requête de recherche. Les opérateurs Google tels que site: et intitle: sont pris en charge.
1 à 2 000 caractèresPar défaut : Non défini
paramsobject / Facultatif
Paramètres de cette requête.
Par défaut : {}
callback_urlstring · nullable / Facultatif
Async et Batch uniquement. URL HTTPS publique de notification sur le port 443, de 2 048 caractères maximum, sans identifiants ni fragment. Omettez ce champ, ou utilisez null ou une chaîne vide pour désactiver les notifications. Dans un Batch, définissez-le pour chaque requête, en dehors de params.
Par défaut : Non défini

Pays, langue et lieu

params.glstring / Facultatif
Code pays à deux lettres, par exemple us, gb, de ou sg. Renseignez-le explicitement pour sélectionner un pays.
Exactement 2 caractèresPar défaut : Non défini
Format accepté^[A-Za-z]{2}$
params.hlstring / Facultatif
Langue de l’interface Google. Renseignez ce champ explicitement pour sélectionner une langue.
1 à 35 caractèresPar défaut : Non défini
Format accepté^[A-Za-z0-9-]+$
params.locationstring / Facultatif
Lieu de recherche demandé, de préférence une ville, par exemple "London, England, United Kingdom". Sa prise en compte dépend du type de recherche.
1 à 200 caractèresPar défaut : Non défini

Pagination

params.numinteger / Facultatif
Nombre de résultats demandé. Si ce champ est omis, FlashData n’ajoute pas de valeur par défaut fixe. Le nombre renvoyé peut varier selon la requête et le type de recherche.
1 à 100, nombres entiersPar défaut : Non défini
params.pageinteger / Facultatif
Numéro de la page de résultats demandée. Renseignez-le explicitement. Chaque page nécessite une requête API distincte.
1 à 100, nombres entiersPar défaut : Non défini

Filtres de recherche

params.tbsstring / Facultatif
Filtres de recherche Google demandés, par exemple qdr:d pour les dernières 24 heures ou qdr:w pour les sept derniers jours. Leur disponibilité dépend du type de recherche.
1 à 200 caractèresPar défaut : Non défini
params.autocorrectboolean / Facultatif
Utilisez true pour demander la correction orthographique, ou false pour demander sa désactivation. Le comportement dépend du type de recherche ; omettez ce champ pour conserver le comportement de Google.
true ou falsePar défaut : Non défini

Réponse

Le mode temps réel renvoie status: done avec les résultats de recherche dans results[0]. Les résultats correspondants se trouvent dans results[0].images. usage.credits indique les crédits facturés.

Le champ imageUrl désigne l’image d’origine ; link désigne sa page source. Les dimensions et les vignettes sont facultatives. Les résultats contiennent des URL et des métadonnées, pas les fichiers image.

Lire le résultat

Enregistrez la réponse JSON d’une requête réussie dans response.json. Enregistrez le script ci-dessous dans read-response.py, dans le même dossier, puis exécutez python read-response.py. Il utilise uniquement la bibliothèque standard de Python et n’envoie aucune nouvelle requête.

read-response.py
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = [
    {"title": item.get("title"), "imageUrl": item.get("imageUrl"), "sourcePage": item.get("link")}
    for item in result.get("images", [])
]
print(json.dumps(output, ensure_ascii=False, indent=2))

Les champs disponibles dépendent de la requête et du type de recherche. Les champs facultatifs peuvent être absents, et des champs supplémentaires peuvent être renvoyés.

Le nombre d’éléments renvoyés et searchParameters.num peuvent différer de params.num. Comptez les éléments du tableau renvoyé pour connaître le nombre réel de résultats.

Tous les champs de réponse
ChampDescription
sourcestringSource API demandée.
statusstringdone lorsque la requête realtime réussit.
created_atstringDate et heure de création de la réponse au format ISO 8601.
usage.creditsnumberCrédits facturés pour la requête selon votre offre.
results[0].searchParametersobjectParamètres de recherche renvoyés par Google, avec la requête dans le champ q. Ces paramètres peuvent différer des valeurs demandées.
results[0].imagesarrayRésultats de recherche d’images.
results[0].images[].titlestringTitre de l’image.
results[0].images[].imageUrlstringURL de l’image d’origine.
results[0].images[].imageWidthinteger · optionalLargeur de l’image d’origine en pixels.
results[0].images[].imageHeightinteger · optionalHauteur de l’image d’origine en pixels.
results[0].images[].thumbnailUrlstring · optionalURL de la vignette.
results[0].images[].thumbnailWidthinteger · optionalLargeur de la vignette en pixels.
results[0].images[].thumbnailHeightinteger · optionalHauteur de la vignette en pixels.
results[0].images[].linkstringPage contenant l’image.
results[0].images[].sourcestring · optionalNom du site source.
results[0].images[].domainstring · optionalDomaine du site source.
results[0].images[].positionintegerPosition du résultat.
results[0].images[].googleUrlstring · optionalURL du résultat Google Images, lorsqu’elle est disponible.

Les champs ci-dessus décrivent la réponse JSON par défaut. Formats JSON, texte brut et Markdown.

Cycle de traitement Async et Batch

La soumission renvoie un reçu, pas les résultats. Async crée une tâche ; Batch renvoie une tâche distincte dans queries[] pour chaque requête acceptée. Suivez chaque tâche et récupérez ses résultats séparément.

Soumettez les requêtes à data.flashdata.dev ; lisez l’état et les résultats sur api.flashdata.dev avec la même clé X-API-Key. Les exemples liés dans les bases de l’API utilisent Python et cURL.

  1. 1. Enregistrer les identifiants de tâche

    Conservez les champs de requête de cette source en passant à Async. Pour Batch, placez chaque requête dans le tableau queries d’un objet JSON. Enregistrez tous les identifiants de tâche renvoyés.

    Requête Async et reçu de soumission · Corps de requête Batch

  2. 2. Vérifier l’état

    GET https://api.flashdata.dev/v2/jobs/{jobId}

    pending / processing : attendez entre les vérifications et respectez Retry-After lorsqu’il est présent. completed : récupérez les résultats. failed : consultez job.error.

    Lisez job.status, et non le champ status du reçu de soumission.

    Vérifier l’état · Python et cURL

    Référence API : état d’une tâche
  3. 3. Récupérer les résultats

    GET https://api.flashdata.dev/v2/jobs/{jobId}/results

    Après la fin du traitement, authentifiez la requête de lecture du résultat, puis récupérez l’URL de stockage renvoyée par la redirection 302, sans votre clé API. Enregistrez le JSON dans les 24 heures suivant la fin du traitement.

    Récupérer les résultats · Python et cURL · Formats de réponse

    Référence API : récupération des résultats

La vérification de l’état et la récupération de résultats existants ne consomment aucun crédit de requête. Un délai de vérification dépassé n’annule pas la tâche : conservez son identifiant pour éviter de soumettre des doublons facturables. Codes d’erreur et nouvelles tentatives.

Webhooks de fin de tâche

Configurer chaque requête

Définissez callback_url à la racine d’une requête Async, ou dans chaque requête d’un Batch, en dehors de params. Aucune requête distincte d’enregistrement de webhook n’est nécessaire. Les requêtes Realtime n’envoient pas de notifications.

Utilisez une URL HTTPS publique sur le port 443. FlashData envoie une notification POST pour chaque tâche atteignant l’état completed ou failed ; l’événement contient des liens, pas le résultat lui-même.

Accuser réception et vérifier

Renvoyez 2xx après avoir enregistré durablement l’événement. Dédupliquez à l’aide de delivery_id, également envoyé dans X-Delivery-Id. Les redirections ne sont pas suivies.

Les envois en échec sont retentés avec un délai exponentiel, dans la limite de 8 tentatives au total et au plus tard 24 heures après la fin du traitement. Conservez la vérification périodique de l’état comme solution de secours.

Les notifications ne sont pas signées. Vérifiez l’identifiant, la source et l’état final de la tâche via l’endpoint d’état authentifié avant de traiter la notification. L’identifiant d’envoi sert à la déduplication ; il ne prouve pas l’authenticité.

Exemple d’événement webhook et ses champs
Exemple de notification de fin de tâche
{
  "delivery_id": "completion:job_example0001",
  "id": "job_example0001",
  "source": "google_images",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_example0001",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
      "method": "GET"
    }
  ]
}
ChampDescription
delivery_idstringIdentifiant de livraison stable. Utilisez-le pour dédupliquer les notifications ; il est aussi envoyé dans l’en-tête X-Delivery-Id.
idstringIdentifiant de la tâche.
sourcestringSource de données demandée.
statusstringcompleted ou failed.
linksarrayLiens vers l’état et les résultats. Les notifications ne contiennent ni les résultats ni de clé API.
links[].relstringself ou results.
links[].hrefstringURL absolue de l’API de gestion ; authentifiez la requête avec votre clé API.
links[].methodstringGET.

Contrat complet des webhooks et restrictions des URL

Résoudre les erreurs

Une recherche terminée peut contenir moins de résultats que demandé. Vérifiez gl, hl, le lieu et les filtres ; les champs facultatifs des résultats enrichis peuvent être absents.

Pour les erreurs d’authentification, de solde, de format de requête ou de limite de débit, consultez la référence commune des erreurs. Une soumission ayant dépassé le délai d’attente peut tout de même avoir créé une tâche ; vérifiez les tâches existantes avant de réessayer.

Erreurs et codes d’état · Quand réessayer · Limites de débit

Guide étape par étape : Choisir et affiner une recherche Google

Tarifs

PlansTarifs d’utilisationpour 1 000 requêtesAbonnementsCrédits inclus par période de facturation
Paiement à l’usage1,00 $USPas de frais mensuelsRechargez selon vos besoins
Micro0,80 $US49,00 $US / mois1 000 crédits (50,00 $US d’utilisation de l’API) inclus
Starter0,65 $US199,00 $US / mois4 000 crédits (200,00 $US d’utilisation de l’API) inclus
Pro0,60 $US499,00 $US / mois10 000 crédits (500,00 $US d’utilisation de l’API) inclus
Scale0,50 $US999,00 $US / mois20 000 crédits (1 000,00 $US d’utilisation de l’API) inclus
Business0,40 $US1 999,00 $US / mois40 000 crédits (2 000,00 $US d’utilisation de l’API) inclus

Un seul forfait par compte. Des crédits partagés entre les trois produits. L’utilisation couverte par les crédits inclus n’est pas facturée à nouveau.

Tarifs actuels et limites des forfaits