# FlashData API Google Places

Recherchez des établissements et des lieux. Récupérez leurs noms, adresses, coordonnées géographiques, notes et coordonnées de contact lorsqu’ils sont disponibles.

Référence canonique : https://flashdata.dev/fr/docs/sources/google_places
Révisé le : 2026-10-23

Endpoint: POST https://data.flashdata.dev/v1/queries/realtime
Authentification: X-API-Key: YOUR_API_KEY
Modes: [Temps réel](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#realtime) · [Asynchrone](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md#batch)

Autorisation requise pour la source: google_places

Remplacez YOUR_API_KEY par une clé API disposant de la permission requise pour cette source et d’un solde de crédits disponible. Exécutez les requêtes sur votre serveur ou dans l’environnement de votre agent.

[Configurer l’authentification](https://flashdata.dev/fr/docs/guides/headers-and-authentication/reference.md)

[Choisir et affiner une recherche Google](https://flashdata.dev/fr/docs/guides/google-search-guide/reference.md)

<a id="quickstart"></a>

## Envoyer une requête

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "google_places",
    "query": "coffee in san francisco",
    "params": {
        "gl": "us",
        "hl": "en",
        "num": 10,
        "page": 1,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries/realtime" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "google_places",
  "query": "coffee in san francisco",
  "params": {
    "gl": "us",
    "hl": "en",
    "num": 10,
    "page": 1
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## Paramètres

<a id="parameters-group-0"></a>

### Corps de la requête

| Paramètre | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Oui | — | Définissez ce champ sur google_places.  |
| <a id="parameter-query"></a> query | string | Oui | Non défini | Requête de recherche. Les opérateurs Google tels que site: et intitle: sont pris en charge. Longueur minimale : 1. Longueur maximale : 2000. |
| <a id="parameter-params"></a> params | object | Non | {} | Paramètres de cette requête.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | Non | Non défini | 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.  |

<a id="parameters-group-1"></a>

### Pays, langue et lieu

| Paramètre | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-gl"></a> params.gl | string | Non | Non défini | Code pays à deux lettres, par exemple us, gb, de ou sg. Renseignez-le explicitement pour sélectionner un pays. Longueur minimale : 2. Longueur maximale : 2. Format : ^[A-Za-z]{2}$ |
| <a id="parameter-params-hl"></a> params.hl | string | Non | Non défini | Langue de l’interface Google. Renseignez ce champ explicitement pour sélectionner une langue. Longueur minimale : 1. Longueur maximale : 35. Format : ^[A-Za-z0-9-]+$ |
| <a id="parameter-params-location"></a> params.location | string | Non | Non défini | 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. Longueur minimale : 1. Longueur maximale : 200. |

<a id="parameters-group-2"></a>

### Pagination

| Paramètre | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-num"></a> params.num | integer | Non | Non défini | 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. Minimum : 1. Maximum : 100. |
| <a id="parameter-params-page"></a> params.page | integer | Non | Non défini | Numéro de la page de résultats demandée. Renseignez-le explicitement. Chaque page nécessite une requête API distincte. Minimum : 1. Maximum : 100. |

<a id="parameters-group-3"></a>

### Filtres de recherche

| Paramètre | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-tbs"></a> params.tbs | string | Non | Non défini | 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. Longueur minimale : 1. Longueur maximale : 200. |
| <a id="parameter-params-autocorrect"></a> params.autocorrect | boolean | Non | Non défini | 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.  |

<a id="response"></a>

## 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

```python
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 = [
    {name: item.get(name) for name in ("title", "address", "latitude", "longitude", "website")}
    for item in result.get("places", [])
]
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## Exemple de réponse

Exemple enregistré ; les champs et les nombres de résultats dépendent de la source et des paramètres de la requête.
```json
{
  "source": "google_places",
  "status": "done",
  "results": [
    {
      "searchParameters": {
        "q": "coffee in san francisco",
        "gl": "us",
        "hl": "en",
        "type": "places",
        "num": 10,
        "page": 1,
        "engine": "google"
      },
      "places": [
        {
          "position": 1,
          "title": "Kopê House",
          "address": "546 Laguna St",
          "latitude": 37.776222,
          "longitude": -122.42606,
          "rating": 4.9,
          "ratingCount": 76,
          "priceLevel": "$1–10",
          "category": "Cafe",
          "cid": "7430826673754830499"
        },
        {
          "position": 2,
          "title": "The Coffee Berry SF",
          "address": "1410 Lombard St",
          "latitude": 37.80141,
          "longitude": -122.424995,
          "rating": 4.9,
          "ratingCount": 642,
          "priceLevel": "$1–10",
          "category": "Coffee shop",
          "cid": "5181132708478222499"
        },
        {
          "position": 3,
          "title": "Sightglass Coffee",
          "address": "270 7th St",
          "latitude": 37.77704,
          "longitude": -122.40844,
          "rating": 4.4,
          "ratingCount": 3400,
          "priceLevel": "$10–20",
          "category": "Coffee shop",
          "cid": "13926460886861596347"
        },
        {
          "position": 4,
          "title": "Origin Lab Coffee & Matcha",
          "address": "211 Sutter St",
          "latitude": 37.789722,
          "longitude": -122.404175,
          "rating": 4.7,
          "ratingCount": 624,
          "priceLevel": "$1–10",
          "category": "Coffee shop",
          "cid": "9114931074474087601"
        },
        {
          "position": 5,
          "title": "The Coffee Movement",
          "address": "1737 Balboa St",
          "latitude": 37.7765,
          "longitude": -122.477806,
          "rating": 4.8,
          "ratingCount": 623,
          "priceLevel": "$1–10",
          "category": "Coffee shop",
          "cid": "2726196137705445702"
        },
        {
          "position": 6,
          "title": "Third Wheel Coffee",
          "address": "991 Oak St",
          "latitude": 37.77323,
          "longitude": -122.43559,
          "rating": 4.9,
          "ratingCount": 266,
          "priceLevel": "$1–10",
          "category": "Coffee shop",
          "cid": "1837357391573517555"
        },
        {
          "position": 7,
          "title": "Better Half Coffee",
          "address": "1448 Pacific Ave",
          "latitude": 37.79555,
          "longitude": -122.41909,
          "rating": 4.9,
          "ratingCount": 123,
          "priceLevel": "$10–20",
          "category": "Coffee shop",
          "cid": "11196405476986641272"
        },
        {
          "position": 8,
          "title": "Sextant Coffee Roasters",
          "address": "1415 Folsom St",
          "latitude": 37.772472,
          "longitude": -122.412964,
          "rating": 4.4,
          "ratingCount": 746,
          "priceLevel": "$1–10",
          "category": "Coffee shop",
          "cid": "16500984014294458956"
        },
        {
          "position": 9,
          "title": "Doppio Coffee & Brunch",
          "address": "1551 Mission St",
          "latitude": 37.773315,
          "longitude": -122.418015,
          "rating": 4.8,
          "ratingCount": 494,
          "priceLevel": "$10–20",
          "category": "Coffee shop",
          "cid": "16475263059648961979"
        },
        {
          "position": 10,
          "title": "Delah Coffee",
          "address": "370 4th St",
          "latitude": 37.781017,
          "longitude": -122.40022,
          "rating": 4.6,
          "ratingCount": 1200,
          "priceLevel": "$10–20",
          "category": "Coffee shop",
          "cid": "10682847123881919373"
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.02
  },
  "created_at": "2026-09-16T07:41:45.679Z"
}
```

## Champs de réponse

| Champ | Type | Description |
| --- | --- | --- |
| source | string | Source API demandée. |
| status | string | done lorsque la requête realtime réussit. |
| created_at | string | Date et heure de création de la réponse au format ISO 8601. |
| usage.credits | number | Crédits facturés pour la requête selon votre offre. |
| results[0].searchParameters | object | Paramè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].places | array | Résultats de recherche locale. |
| results[0].places[].title | string | Nom du lieu ou de l’établissement. |
| results[0].places[].address | string · optional | Adresse postale. |
| results[0].places[].latitude | number · optional | Latitude. |
| results[0].places[].longitude | number · optional | Longitude. |
| results[0].places[].rating | number · optional | Note moyenne. |
| results[0].places[].ratingCount | integer · optional | Nombre d’évaluations. |
| results[0].places[].category | string · optional | Catégorie de l’établissement. |
| results[0].places[].phoneNumber | string · optional | Numéro de téléphone indiqué. |
| results[0].places[].website | string · optional | Site web de l’établissement. |
| results[0].places[].cid | string · optional | Identifiant Google du lieu. |
| results[0].places[].position | integer | Position du résultat. |
| results[0].places[].priceLevel | string · optional | Niveau de prix affiché, lorsqu’il est disponible. |

- 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.

## Formats de réponse

Les réponses sont en JSON par défaut. Choisissez un autre format avec ces en-têtes facultatifs.

- Accept: application/json (par défaut) ou text/plain. Le texte brut présente les mêmes champs dans une disposition lisible avec indentation.
- X-Respond-With: markdown. Ne définissez pas cet en-tête pour conserver les champs d’origine. Markdown fonctionne avec les deux formats de réponse.

Markdown est disponible pour les requêtes realtime et les résultats de tâches terminées.

Les champs ci-dessous décrivent la réponse JSON par défaut.

[Exemples de formats de requête et de réponse](https://flashdata.dev/fr/docs/guides/response-formats/reference.md#headers)

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## Bases de l’API

Le générateur de requêtes et les exemples ci-dessus utilisent les paramètres de cette source. Consultez les exemples Python et cURL ci-dessous pour les étapes communes de soumission, de suivi et de récupération des résultats. Le corps d’une requête Batch est un objet JSON contenant queries ; chaque élément renvoie son propre identifiant de tâche.

- [Requête Async et reçu de soumission](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [Vérifier l’état de la tâche](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [Récupérer les résultats des tâches terminées](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#results)
- [Requêtes JSON Batch](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md#batch)
- [Spécification OpenAPI publique](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Notifications d'achèvement

- [Recevoir et vérifier les webhooks de fin de traitement](https://flashdata.dev/fr/docs/guides/async-batch/reference.md#webhooks)

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

## Dépannage

- [Erreurs et codes d’état](https://flashdata.dev/fr/docs/errors/reference.md#status-codes)
- [Quand réessayer](https://flashdata.dev/fr/docs/errors/reference.md#retries)

## API associées

- [API Google Search](https://flashdata.dev/fr/docs/sources/google_search/reference.md)
- [API Google Images](https://flashdata.dev/fr/docs/sources/google_images/reference.md)
