API Maps Tools Resolution (sperimentale)

L'API Maps Tools Resolution fornisce endpoint di elaborazione batch per risolvere i nomi e gli URL delle località in ID luogo di Google Maps.

Accesso e autenticazione API

Metodi di autenticazione

Le API supportano le credenziali chiave API e OAuth 2.0:

1. Chiave API

Puoi autenticare le richieste aggiungendo una chiave API di Google Maps Platform valida all'URL della richiesta o nell'intestazione X-Goog-Api-Key:

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. Ambiti OAuth 2.0

Se utilizzi l'autorizzazione OAuth, sono supportati i seguenti ambiti:

  • https://www.googleapis.com/auth/maps-platform.mapstools (consigliato)

Convalida e vincoli delle richieste

Per evitare un carico eccessivo e garantire tempi di risposta rapidi, le richieste batch vengono convalidate rigorosamente:

  • Limite di dimensioni batch: entrambe le API consentono un massimo di 20 elementi per richiesta.
  • Requisiti di ResolveNames:
    • Ogni elemento delle query deve specificare un parametro di testo non vuoto.
    • Le query devono rappresentare un nome o un indirizzo di un luogo specifico (ad es. "Googleplex, Mountain View, CA", "Torre Eiffel, Parigi").
    • Le ricerche di categorie generali (ad es. "ristoranti a New York") o i nomi di catene generici senza una località (ad es. "Starbucks") non sono supportati e la risoluzione potrebbe non riuscire.
  • Requisiti di ResolveMapsUrls:
    • Ogni URL deve essere un URL di Google Maps valido dal punto di vista strutturale.
    • I formati supportati includono:
      • URL del luogo standard: https://www.google.com/maps/place/...
      • URL abbreviato: https://maps.app.goo.gl/...
    • Gli URL di Maps basati su query generali (ad es. https://maps.google.com/?q=restaurant) e gli URL che non rimandano a un singolo luogo univoco non sono supportati.

Gestione degli errori parziali

Entrambe le API sono progettate come processori batch. Se la risoluzione di alcuni elementi di un batch non riesce, la richiesta complessiva non genera un errore di primo livello. L'API restituisce invece una risposta Riuscita parziale.

Come interpretare la risposta

  1. Allineamento 1:1 garantito: gli elenchi di risultati restituiti (per ResolveNames) o di entità (per ResolveMapsUrls) vengono mappati 1:1 con l'elenco di input.
  2. Elementi vuoti per gli errori: se la risoluzione di un elemento all'indice i non è riuscita, l'elenco dei risultati conterrà un oggetto vuoto {} all'indice i.
  3. Mappa failedRequests: la risposta contiene una mappa failedRequests.
    • La chiave è l'indice in base 0 dell'elemento non riuscito (rappresentato come stringa in JSON).
    • Il valore è un oggetto google.rpc.Status contenente il codice di errore specifico (dagli stati gRPC/HTTP standard) e un messaggio dettagliato che spiega il motivo dell'errore.

Errori di primo livello

Viene restituito un errore HTTP di primo livello (ad es. 400 Bad Request) solo se la convalida della richiesta non riesce (ad es. quando vengono passati più di 20 elementi o mancano campi obbligatori).

Specifiche API ed esempi di cURL

1. API ResolveNames

Metodo: POST

https://mapstools.googleapis.com/v1alpha:resolveNames

Formato del corpo della richiesta

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}
  • queries (obbligatorio): elenco ripetuto di query da risolvere (max. 20).
  • locationBias (facoltativo): riquadro di delimitazione della finestra per orientare i risultati verso una regione locale.
  • regionCode (facoltativo): codice paese CLDR (ad es. "US", "FR") per orientare i risultati.

Esempio di cURL: risoluzione riuscita

Questa query risolve "Googleplex" e "Torre Eiffel".

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"
Risposta JSON
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Esempio di cURL: risultati misti (errore parziale)

In questo esempio, il primo elemento è un testo spazzatura non risolvibile, mentre il secondo è un luogo valido.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"
Risposta JSON
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. API ResolveMapsUrls

Metodo: POST

https://mapstools.googleapis.com/v1alpha:resolveMapsUrls

Formato del corpo della richiesta

{
  "urls": [
    "string"
  ]
}
  • urls (obbligatorio): elenco ripetuto di stringhe di URL di Google Maps da risolvere (max. 20).

Esempio di cURL: risoluzione riuscita

Risoluzione di un link a un luogo standard di Google Maps.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
Risposta JSON
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Esempio di cURL: risultati misti (errore parziale)

Risoluzione di un URL di un luogo valido e di un URL non valido/non supportato.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
Risposta JSON
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Esempio di cURL: errore di convalida

Tentativo di passare più di 20 URL in un'unica richiesta.

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
Risposta JSON
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}