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 di Maps Grounding Lite:

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, vedi Attivare il servizio Maps Grounding Lite nel progetto Google Cloud.

Accesso API e autenticazione

L'API Resolution supporta sia le chiavi API sia le credenziali 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 in 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

Le seguenti quote predefinite si applicano all'API Resolution:

• 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 $) in base allo 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 dimensioni 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 categoriche generali (ad esempio "ristoranti a New York") o i nomi di catene generici senza una località (ad esempio "Starbucks") non sono supportate e potrebbero non essere risolte.
• 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 generiche (ad esempio, https://maps.google.com/?q=restaurant) e gli URL che non rimandano a un singolo luogo unico non sono supportati.

Salvare 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 unico link a Maps che contiene tutti i luoghi risolti correttamente nel batch. Mostra 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 nel batch viene risolto, la risposta non include saveToMapsUrl.

Gestire gli errori parziali

Entrambi i metodi sono processori batch. Se la risoluzione di alcuni elementi di un batch non va a buon fine, la richiesta complessiva non genera un errore di primo livello. L'API restituisce invece una risposta di completamento parziale e devi controllare la risposta per gli errori per elemento.

Interpreta la risposta

1. Allineamento 1:1 garantito: l'elenco results restituito (per ResolveNames) o l'elenco entities (per ResolveMapsUrls) corrisponde 1:1 all'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 perché l'elemento non è riuscito.
4. saveToMapsUrl copre solo i successi: 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 riuscito perché un elemento non è andato a buon fine. Controlla sempre failedRequests per scoprire quali elementi, se presenti, non sono stati risolti.

Errori per elemento

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

Riprova solo gli elementi non riusciti 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 ha query o ha una query con un valore text vuoto oppure una richiesta ResolveMapsUrls ha un URL vuoto o non valido dal punto di vista sintattico. Un elemento non valido causa l'esito negativo dell'intera richiesta.
• Errori di autenticazione, autorizzazione o quota: ad esempio, la chiave API non è presente o non è valida oppure la richiesta supera i limiti di utilizzo.
• Errori del server (500 INTERNAL): riprova a inviare la richiesta.

Utilizzare 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 batch di nomi di località o indirizzi in ID luogo.
• resolve_maps_urls: Risolve un batch di URL di Google Maps in ID luogo.

Quando configuri il tuo LLM per utilizzare il server MCP Maps Grounding Lite, questi strumenti sono disponibili insieme agli altri strumenti 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 al modello 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.

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 trasmetti 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).
• (Facoltativo) locationBias: riquadro di delimitazione dell'area visibile per orientare i risultati verso una regione locale.
• regionCode (Facoltativo): codice paese CLDR (ad es. "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 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 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: convalida non riuscita

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 di monitoraggio problemi pubblico di Maps Grounding Lite:

• Segnala un bug
• Invia una richiesta di funzionalità
• Invia feedback