Premiers pas avec l'API Geocoding v4

Développeurs de l'Espace économique européen (EEE)

Si votre adresse de facturation se trouve dans l'Espace économique européen, les Conditions d'utilisation de Google Maps Platform pour l'EEE s'appliqueront à votre utilisation des Services à compter du 8 juillet 2025. La fonctionnalité varie selon la région. En savoir plus

Avant de commencer  : Avant de commencer à utiliser l'API Geocoding, vous devez disposer d'un projet avec un compte de facturation, et activer et l'API Geocoding . Nous vous recommandons de désigner plusieurs propriétaires du projet et plusieurs administrateurs de la facturation afin que vous ayez toujours quelqu'un de disponible pour ces rôles dans votre équipe. Pour en savoir plus, consultez Configurer vos projets dans la console Cloud.

L'API Geocoding v4 propose deux grandes familles de fonctionnalités : la recherche de destinations pour des attributs hyperlocaux enrichis et le géocodage de base (conversion de coordonnées en adresses). Vous ne savez pas quelle méthode utiliser ? Consultez Choisir une méthode de géocodage.

• Rechercher des destinations (SearchDestinations) : récupère des informations détaillées sur l'arrivée à une destination, y compris les entrées des bâtiments, les points de navigation routables, les contours des bâtiments/terrains, les sous-destinations et les points de repère à proximité.
• Geocoding (GeocodeAddress) : convertit les adresses postales en coordonnées de latitude et de longitude pour placer des repères de base ou centrer une carte.
• Geocoding inversé (GeocodeLocation) : convertit des coordonnées géographiques en adresse postale lisible par l'humain.
• Géocodage de lieu (GeocodePlace) : recherche l'adresse formatée et les coordonnées d'un ID de lieu connu.

Exemples de requêtes et de réponses

Vous accédez à l'API Geocoding via une interface HTTP. Vous trouverez ci-dessous des exemples de démarrage rapide pour rechercher des destinations, le geocoding et le geocoding inversé.

Requête et réponse de recherche de destinations (données d'arrivée hyperlocales)

L'exemple suivant envoie une requête HTTP POST à SearchDestinations pour "1600 Amphitheatre Parkway, Mountain View, CA". Notez que SearchDestinations nécessite un en-tête X-Goog-FieldMask spécifiant les champs à renvoyer :

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "1600 Amphitheatre Parkway, Mountain View, CA"
  }
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.formattedAddress,destinations.primary.location,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/destinations"

Vous trouverez ci-dessous un exemple de réponse SearchDestinations montrant le polygone de l'empreinte du bâtiment, les entrées préférées, les points de navigation routables et les points de repère à proximité :

{
  "destinations": [
    {
      "primary": {
        "displayName": { "text": "Googleplex", "languageCode": "en" },
        "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
        "location": { "latitude": 37.4220656, "longitude": -122.0840897 },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [-122.084958, 37.422145],
              [-122.084112, 37.422610],
              [-122.083510, 37.421980],
              [-122.084958, 37.422145]
            ]
          ]
        }
      },
      "entrances": [
        {
          "location": { "latitude": 37.422189, "longitude": -122.084215 },
          "tags": ["PREFERRED"]
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "Eg...",
          "displayName": { "text": "Amphitheatre Pkwy Dropoff", "languageCode": "en" },
          "location": { "latitude": 37.421912, "longitude": -122.084301 },
          "travelModes": ["DRIVE"],
          "usages": ["DROPOFF", "PICKUP"]
        }
      ],
      "landmarks": [
        {
          "place": { "displayName": { "text": "Charleston Park", "languageCode": "en" } },
          "relationalDescription": { "text": "Adjacent to Charleston Park", "languageCode": "en" },
          "straightLineDistanceMeters": 85.4
        }
      ]
    }
  ]
}

Requête de géocodage et réponse (recherche de latitude/longitude)

L'exemple suivant demande la latitude et la longitude de "1600 Amphitheatre Parkway, Mountain View, CA" et spécifie que la sortie doit être au format JSON.

curl -H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Vous pouvez tester cela en saisissant l'URL dans votre navigateur Web (veillez à remplacer YOUR_API_KEY par votre clé API réelle). La réponse inclut la latitude et la longitude de l'adresse.

Consultez le guide du développeur pour en savoir plus sur la création d'URL de requête de géocodage, les paramètres disponibles et l' interprétation de la réponse.

Un exemple de réponse à une requête de géocodage est fourni ci-dessous, au format JSON :

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "placeId": "ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "location": {
        "latitude": 37.4438238,
        "longitude": -122.0869895
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4424748197085,
          "longitude": -122.0883384802915
        },
        "high": {
          "latitude": 37.445172780291493,
          "longitude": -122.08564051970852
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

Requête de géocodage inversé et réponse (recherche d'une adresse)

L'exemple suivant demande l'adresse correspondant à une latitude/longitude donnée à Brooklyn, NY, États-Unis. Il indique également que la réponse doit être au format JSON.

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=YOUR_API_KEY

Vous pouvez tester cela en saisissant l'URL dans votre navigateur Web (veillez à remplacer "YOUR_API_KEY" par votre clé API réelle). La réponse inclut une adresse lisible par l'humain pour la latitude et la longitude.

Pour en savoir plus sur la création d'URL de requête de géocodage inversé, les paramètres disponibles et l' interprétation de la réponse, consultez le guide du développeur.

Un exemple de réponse à une requête de géocodage inversé est fourni ci-dessous, au format JSON :

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "location": {
        "latitude": 37.4225657,
        "longitude": -122.08465439999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421214719708509,
          "longitude": -122.08603273029148
        },
        "high": {
          "latitude": 37.423912680291508,
          "longitude": -122.0833347697085
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4225178,
          "longitude": -122.08484599999998
        },
        "high": {
          "latitude": 37.422609600000008,
          "longitude": -122.0845215
        }
      },
      "formattedAddress": "Google Building 40, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "Google Building 40",
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 40",
          "shortText": "Google Building 40",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address",
        "subpremise"
      ]
    },
    ... Additional results truncated in this example[] ...
}

Authentification, quotas, tarifs et règles

Authentification

Pour utiliser l'API Geocoding, vous devez d'abord l'activer et obtenir les identifiants d'authentification appropriés. Pour en savoir plus, consultez Premiers pas avec Google Maps Platform.

Quotas et tarifs

Consultez la page Utilisation et facturation pour en savoir plus sur les quotas et les tarifs de l'API Geocoding.

Remarque : Pendant la preview, les méthodes de l'API Geocoding v4 sont limitées à 25 requêtes par seconde (RPS). Pour savoir comment demander une augmentation de quota, consultez Afficher et gérer les quotas, puis sélectionnez API Geocoding comme service.

Avertissement : En raison des risques de sécurité, vous ne devez pas appeler les méthodes de l'API Geocoding v4 directement à partir du code JavaScript côté client. Si vous le faites malgré les recommandations, sachez que demander des quotas plus élevés augmente l'impact potentiel d'une utilisation abusive de la clé API. Consultez Points à noter concernant la sécurité.

Règles

L'utilisation de l'API Geocoding doit être conforme aux Règles de l'API.