Inizia a utilizzare l'API Geocoding v4

Sviluppatori dello Spazio economico europeo (SEE)

Se il tuo indirizzo di fatturazione si trova nello Spazio economico europeo, a partire dall'8 luglio 2025, i Termini di servizio di Google Maps Platform per il SEE si applicheranno al tuo utilizzo dei servizi. La funzionalità varia in base alla regione. Scopri di più.

Prima di iniziare: Prima di iniziare a utilizzare l'API Geocoding, devi avere un progetto con un account di fatturazione e l' API Geocoding abilitata. Ti consigliamo di creare più Project Owner e Amministratori fatturazione, in modo da avere sempre a disposizione del tuo team qualcuno con questi ruoli. Per saperne di più, consulta Configura nella console Cloud.

L'API Geocoding v4 offre due famiglie di funzionalità principali: la ricerca della destinazione per attributi iperlocali avanzati e la geocodifica di base (conversione di coordinate in indirizzi). Non sai quale metodo utilizzare? Consulta Scegli un metodo di geocodifica.

• Cerca destinazioni (SearchDestinations): recupera dettagli completi sull'arrivo per una destinazione, inclusi gli ingressi degli edifici, i punti di navigazione percorribili, i contorni degli edifici/terreni, le destinazioni secondarie e i punti di riferimento nelle vicinanze.
• Geocoding (GeocodeAddress): converte gli indirizzi in coordinate di latitudine e longitudine per posizionare indicatori di base o centrare una mappa.
• Geocodifica inversa (GeocodeLocation): converte le coordinate geografiche in un indirizzo leggibile.
• Geocodifica dei luoghi (GeocodePlace): trova l'indirizzo formattato e le coordinate di un ID luogo noto.

Richieste e risposte di esempio

Puoi accedere all'API Geocoding tramite un'interfaccia HTTP. Di seguito sono riportati esempi di guide rapide per Cerca destinazioni, geocodifica diretta e geocodifica inversa.

Richiesta e risposta di ricerca di destinazioni (dati di arrivo iperlocali)

L'esempio seguente invia una richiesta HTTP POST a SearchDestinations per "1600 Amphitheatre Parkway, Mountain View, CA". Tieni presente che SearchDestinations richiede un'intestazione X-Goog-FieldMask che specifichi i campi da restituire:

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"

Di seguito è riportato un esempio di risposta SearchDestinations che mostra il poligono del perimetro dell'edificio, gli ingressi preferiti, i punti di navigazione percorribili e i punti di riferimento nelle vicinanze:

{
  "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
        }
      ]
    }
  ]
}

Richiesta e risposta di geocodifica (ricerca di latitudine/longitudine)

L'esempio seguente richiede la latitudine e la longitudine di "1600 Amphitheatre Parkway, Mountain View, CA" e specifica che l'output deve essere in formato JSON.

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

Puoi verificarlo inserendo l'URL nel browser web (assicurati di sostituire YOUR_API_KEY con la tua chiave API effettiva). La risposta include la latitudine e la longitudine dell'indirizzo.

Consulta la guida per gli sviluppatori per ulteriori informazioni sulla creazione di URL di richiesta di geocodifica, sui parametri disponibili e sulla comprensione della risposta.

Di seguito è riportato un esempio di risposta di geocodifica in formato 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"
      ]
    }
  ]
}

Richiesta e risposta di geocodifica inversa (ricerca di indirizzi)

L'esempio seguente richiede l'indirizzo corrispondente a una determinata latitudine/longitudine a Brooklyn, New York, USA. Specifica che l'output deve essere in formato JSON.

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

Puoi verificarlo inserendo l'URL nel browser web (assicurati di sostituire "YOUR_API_KEY" con la tua chiave API effettiva). La risposta include un indirizzo leggibile per la posizione di latitudine e longitudine.

Consulta la guida per gli sviluppatori per ulteriori informazioni sulla creazione di URL di richiesta di geocodifica inversa, sui parametri disponibili e sulla comprensione della risposta.

Di seguito è riportato un esempio di risposta di geocodifica inversa in formato 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[] ...
}

Autenticazione, quote, prezzi e policy

Autenticazione

Per utilizzare l'API Geocoding, devi prima abilitarla e ottenere le credenziali di autenticazione appropriate. Per saperne di più, consulta Inizia a utilizzare Google Maps Platform.

Quote e prezzi

Consulta la pagina Utilizzo e fatturazione per informazioni dettagliate sulle quote e sui prezzi impostati per l'API Geocoding.

Nota: durante l'anteprima, i metodi dell'API Geocoding v4 sono limitati a 25 query al secondo (QPS). Per informazioni su come richiedere una quota più elevata, consulta Visualizza e gestisci le quote e seleziona API Geocoding come servizio.

Attenzione: a causa di rischi per la sicurezza, non devi chiamare i metodi dell'API Geocoding v4 direttamente da JavaScript lato client. Se lo fai nonostante i consigli, tieni presente che la richiesta di quote più elevate aumenta il potenziale impatto dell'abuso delle chiavi API. Consulta Considerazioni sulla sicurezza.

Norme

L'utilizzo dell'API Geocoding deve essere conforme alle norme relative alle API.