API Maps Tools Resolution

L'API Maps Tools Resolution fa parte di Maps Grounding Lite. Fornisce endpoint batch che risolvono i nomi delle località e gli URL di Google Maps in ID luogo di Google Maps. Puoi utilizzare gli ID luogo restituiti con altre API di Google Maps Platform. Ogni risposta include anche un link che salva i luoghi risolti come elenco in Google Maps.

L'API Resolution è disponibile sia come metodi REST sia come strumenti sul server MCP Maps Grounding Lite:

Capacità Metodo REST Strumento MCP
Risolvi i nomi o gli indirizzi delle località in luoghi resolveNames resolve_names
Risolvi gli URL di Google Maps in luoghi resolveMapsUrls resolve_maps_urls

Prima di iniziare

Per utilizzare l'API Resolution, devi disporre di un progetto Google Cloud con fatturazione abilitata e del servizio API Maps Grounding Lite abilitato. Per istruzioni, consulta Attiva il servizio Maps Grounding Lite nel tuo progetto Google Cloud.

Accesso e autenticazione API

L'API Resolution supporta sia le credenziali della chiave API sia quelle di OAuth 2.0.

Chiave API

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

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

Negli esempi di questa pagina, sostituisci API_KEY con la tua chiave API.

Ambiti OAuth 2.0

Se utilizzi l'autorizzazione OAuth, è supportato il seguente ambito:

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

Limiti di utilizzo

All'API Resolution si applicano le seguenti quote predefinite:

  • ResolveNames: 600 query al minuto per progetto.
  • ResolveMapsUrls: 600 query al minuto per progetto.
  • Dimensioni del batch: fino a 20 query o URL per richiesta.

Ogni richiesta viene conteggiata come una query, indipendentemente dal numero di elementi che contiene.

Prezzi

Le richieste a ResolveNames e ResolveMapsUrls vengono fatturate senza costi (0 $) con lo SKU Places API Text Search Essentials (IDs Only). Come per il resto di Maps Grounding Lite, il tuo progetto deve avere un account di fatturazione.

Convalida e vincoli delle richieste

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

  • Limite di dimensione del batch: entrambi i metodi consentono un massimo di 20 elementi per richiesta.
  • Requisiti di ResolveNames:
    • Ogni elemento in queries deve specificare un parametro text non vuoto.
    • Le query devono rappresentare un nome o un indirizzo di un luogo specifico (ad esempio, "Googleplex, Mountain View, CA" o "Torre Eiffel, Parigi").
    • Le ricerche generiche per categoria (ad esempio, "ristoranti a New York") o i nomi generici di catene senza una località (ad esempio, "Starbucks") non sono supportati e potrebbero non essere risolti.
  • Requisiti di ResolveMapsUrls:
    • Ogni URL deve essere un URL di Google Maps strutturalmente valido.
    • Tra i formati supportati:
      • URL del luogo standard: https://www.google.com/maps/place/...
      • URL abbreviato: https://maps.app.goo.gl/...
    • Gli URL di Maps basati su query generiche (ad esempio, https://maps.google.com/?q=restaurant) e gli URL che non rimandano a un singolo luogo univoco non sono supportati.

Salva i luoghi risolti in Google Maps

Se almeno un elemento di un batch viene risolto, la risposta include un campo saveToMapsUrl. Si tratta di un singolo link a Google Maps che contiene tutti i luoghi risolti correttamente nel batch. Presenta questo link agli utenti che vogliono salvare, condividere o aprire i luoghi risolti come elenco in Google Maps.

Utilizza sempre il link restituito dall'API. Non creare il link manualmente. Se nessun elemento del batch viene risolto, la risposta non include saveToMapsUrl.

Gestisci gli errori parziali

Entrambi i metodi sono processori batch. Se alcuni elementi di un batch non vengono risolti, la richiesta complessiva non va a buon fine e viene visualizzato un errore di primo livello. L'API restituisce invece una risposta di esito positivo parziale e devi controllare la risposta per verificare la presenza di errori per elemento.

Interpreta la risposta

  1. Allineamento 1:1 garantito: l'elenco results restituito (per ResolveNames) o l'elenco entities (per ResolveMapsUrls) viene mappato 1:1 con l'elenco di input, per indice.
  2. Elementi vuoti per gli errori: se l'elemento all'indice i non è stato risolto, l'elenco dei risultati contiene 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 e un messaggio che spiega il motivo per cui l'elemento non è riuscito.
  4. saveToMapsUrl copre solo gli esiti positivi: il link saveToMapsUrl include solo gli elementi risolti. Gli elementi non riusciti non sono inclusi.

Non dare per scontato che l'intero batch non sia andato a buon fine perché un elemento non è andato a buon fine. Controlla sempre failedRequests per scoprire quali elementi, se presenti, non è stato possibile risolvere.

Errori per elemento

La tabella seguente elenca gli errori per elemento che potresti visualizzare in failedRequests:

Metodo Causa Codice Messaggio
ResolveNames Il nome o l'indirizzo non possono essere risolti in un luogo. 5 (NOT_FOUND) Place not found.
ResolveMapsUrls L'URL non può essere risolto in un luogo. 3 (INVALID_ARGUMENT) Failed to resolve Maps URL to a place.
Entrambi i metodi Si è verificato un errore interno durante la risoluzione dell'elemento. 13 (INTERNAL) Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support

Riprova solo gli elementi che non sono stati caricati con INTERNAL.

Errori di primo livello

L'API restituisce un errore di primo livello anziché una risposta parziale nei seguenti casi:

  • Richiesta non valida (400 INVALID_ARGUMENT): la richiesta contiene più di 20 elementi, una richiesta ResolveNames non contiene query o contiene una query con un valore text vuoto oppure una richiesta ResolveMapsUrls contiene un URL vuoto o non valido dal punto di vista sintattico. Un elemento non valido causa l'errore dell'intera richiesta.
  • Errori di autenticazione, autorizzazione o quota: ad esempio, la chiave API manca o non è valida oppure la richiesta supera i limiti di utilizzo.
  • Errori del server (500 INTERNAL): riprova a inviare la richiesta.

Utilizza l'API Resolution con MCP

Il server MCP Maps Grounding Lite all'indirizzo https://mapstools.googleapis.com/mcp espone l'API Resolution come due strumenti:

  • resolve_names: risolve un gruppo di nomi o indirizzi di località in ID luogo.
  • resolve_maps_urls: risolve un gruppo di URL di Google Maps in ID luogo.

Quando configuri l'LLM per l'utilizzo del server MCP di Maps Grounding Lite, questi strumenti sono disponibili insieme agli altri strumenti di Maps Grounding Lite. Gli strumenti accettano gli stessi input, applicano gli stessi vincoli e restituiscono la stessa risposta di errore parziale dei metodi REST.

Le risposte dello strumento includono il campo save_to_maps_url. Le descrizioni degli strumenti indicano all'LLM di presentare questo link quando l'utente vuole salvare, condividere o aprire i luoghi risolti come elenco in Google Maps, anziché creare un link autonomamente.

L'esempio seguente utilizza curl per chiamare direttamente lo strumento resolve_names:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Per chiamare resolve_maps_urls, imposta name su resolve_maps_urls e passa un array urls in arguments.

Specifica dell'API REST ed esempi di curl

ResolveNames

Metodo: POST

https://mapstools.googleapis.com/v1: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 (massimo 20).
  • locationBias (facoltativo): riquadro di delimitazione dell'area visibile per orientare i risultati verso una regione locale.
  • regionCode (facoltativo): codice paese CLDR (ad esempio "US" o "FR") per influenzare 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/v1:resolveNames?key=API_KEY"
Risposta JSON
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Esempio di curl: risultati misti (errore parziale)

In questo esempio, il primo elemento è un testo che non può essere risolto, 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/v1:resolveNames?key=API_KEY"
Risposta JSON
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

Metodo: POST

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

Formato del corpo della richiesta

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

Esempio di curl: risoluzione riuscita

L'esempio seguente risolve un URL di un luogo di Google Maps standard:

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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
Risposta JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Esempio di curl: risultati misti (errore parziale)

L'esempio seguente risolve un URL di un luogo valido e un URL che non può essere risolto in un luogo:

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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
Risposta JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Esempio di curl: errore di convalida

L'esempio seguente passa più di 20 URL in una singola 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/v1:resolveMapsUrls?key=API_KEY"
Risposta JSON
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

Invia feedback

Per segnalare un problema o condividere un feedback sull'API Resolution, utilizza il componente Issue Tracker pubblico di Maps Grounding Lite: