Completamento automatico (novità)

Il servizio Autocomplete (New) è un servizio web che restituisce previsioni delle località e delle query in risposta a una richiesta HTTP. Nella richiesta, specifica una stringa di ricerca testuale e limiti geografici che controlli l'area di ricerca.

Il servizio di completamento automatico (nuovo) può creare corrispondenze con le parole complete e le sottostringhe dell'input, risolvendo nomi di luoghi, indirizzi e più codici. Le applicazioni possono quindi inviare query come tipi di utente, per fornire previsioni di query e luoghi in tempo reale.

La risposta dell'API Autocomplete (New) può contenere due tipi di previsioni:

  • Previsioni dei luoghi: luoghi, come attività, indirizzi e punti d'interesse, in base alla stringa di testo di input e all'area di ricerca specificate. Le previsioni dei luoghi vengono restituite per impostazione predefinita.
  • Previsioni delle query: stringhe di query che corrispondono alla stringa di testo di input e all'area di ricerca. Per impostazione predefinita, non vengono restituite le previsioni delle query. Utilizza il parametro di richiesta includeQueryPredictions per aggiungere previsioni delle query alla risposta.

Ad esempio, chiami l'API utilizzando come input una stringa contenente un input parziale dell'utente, "Sicilian piz", con l'area di ricerca limitata a San Francisco, CA. La risposta contiene quindi un elenco di previsioni sui luoghi che corrispondono alla stringa di ricerca e all'area di ricerca, come il ristorante chiamato "Sicilian Pizza Kitchen", insieme ai dettagli sul luogo.

Le previsioni dei luoghi restituite sono progettate per essere presentate all'utente per selezionare più facilmente il luogo desiderato. Puoi effettuare una richiesta Place Details (New) (Dettagli luogo) per ricevere ulteriori informazioni su una qualsiasi delle previsioni di luogo restituite.

La risposta può anche contenere un elenco di previsioni delle query corrispondenti alla stringa di ricerca e all'area di ricerca, ad esempio "Pizza e pasta in Sicilia". Ogni previsione di query nella risposta include il campo text contenente una stringa di ricerca testuale consigliata. Utilizza questa stringa come input per Ricerca testuale (Nuova) per eseguire una ricerca più dettagliata.

Richieste di completamento automatico (nuove)

Una richiesta di completamento automatico (nuova) è una richiesta POST HTTP a un URL nel formato:

https://places.googleapis.com/v1/places:autocomplete

Passa tutti i parametri nel corpo della richiesta JSON o nelle intestazioni come parte della richiesta POST. Ad esempio:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Effettua una richiesta utilizzando il completamento automatico (novità)

L'API Places supporta le API Autocomplete e Query Autocomplete esistenti. Se hai dimestichezza con queste API, la versione di anteprima di Autocomplete (New) apporta le seguenti modifiche:

  • La nuova funzionalità di completamento automatico utilizza richieste POST HTTP. Trasferisci i parametri nel corpo della richiesta o nelle intestazioni come parte di una richiesta POST HTTP. Al contrario, con le API esistenti, i parametri URL vengono trasmessi utilizzando una richiesta HTTP GET.
  • La nuova funzionalità di completamento automatico supporta sia le chiavi API sia i token OAuth come meccanismo di autenticazione.
  • Nel nuovo completamento automatico è supportato solo JSON come formato di risposta.

La seguente tabella elenca i parametri nelle API Autocomplete e Query Autocomplete esistenti che sono stati rinominati o modificati per il nuovo Autocomplete o che non sono più supportati.

Parametro attuale Nuovo parametro Note
components includedRegionCodes
language languageCode
location locationBias
ipbias Se ometti sia locationBias sia locationRestriction, l'API utilizza la differenziazione degli IP per impostazione predefinita.
offset inputOffset
radius locationBias o locationRestriction
region regionCode
stricbounds locationRestriction
sessiontoken sessionToken
types includedPrimaryTypes

Limiti di utilizzo

Durante la release di anteprima, puoi eseguire un massimo di 600 query al minuto per progetto.

Opzioni di supporto per le release in anteprima

Sebbene Google non abbia alcun obbligo di fornire assistenza per le versioni in anteprima, le funzionalità o le funzionalità dei Servizi, valuteremo le richieste in queste fasi di sviluppo caso per caso.

  • Le versioni di pre-release non sono coperte dallo SLA di Google Maps Platform.
  • È consigliabile utilizzare meccanismi di fallback, soprattutto se usi una versione pre-release in un ambiente di produzione. Ecco alcuni esempi di situazioni di riserva: quota superata, latenza e codici di risposta imprevisti o risposte impreviste rispetto al completamento automatico esistente.

Puoi utilizzare Issue Tracker per richiedere nuove funzionalità o suggerire modifiche alle funzionalità esistenti. Descrivi la funzionalità specifica che vorresti che fosse aggiunta, oltre ai motivi per cui ritieni che sia importante. Se possibile, includi dettagli specifici sul tuo caso d'uso e sulle nuove opportunità che la funzionalità consentirebbe:

Per qualsiasi altra domanda sulle funzionalità, invia un'email all'indirizzo newplaceapi@google.com.

Informazioni sulla risposta

Il completamento automatico (nuovo) restituisce un oggetto JSON come risposta. Nella risposta:

  • L'array suggestions contiene tutti i luoghi e le query previsti in ordine in base alla loro pertinenza percepita. Ogni luogo è rappresentato da un campo placePrediction e ogni query è rappresentata da un campo queryPrediction.
  • Un campo placePrediction contiene informazioni dettagliate sulla previsione di una singola località, inclusi l'ID luogo e la descrizione testuale.
  • Un campo queryPrediction contiene informazioni dettagliate su una singola previsione di query.

L'oggetto JSON completo ha il seguente formato:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

Parametri obbligatori

  • input

    La stringa di testo in cui eseguire la ricerca. Specifica parole complete e sottostringhe, nomi di luoghi, indirizzi e più codici. Il servizio di completamento automatico (nuovo) restituisce le corrispondenze candidati in base a questa stringa e ordina i risultati in base alla pertinenza percepita.

Parametri facoltativi

  • includedPrimaryTypes

    Un luogo può avere un solo singolo tipo principale associato ai tipi Tabella A o Tabella B. Ad esempio, il tipo principale potrebbe essere "mexican_restaurant" o "steak_house".

    Per impostazione predefinita, l'API restituisce tutte le posizioni in base al parametro input, indipendentemente dal valore del tipo principale associato al luogo. Limita i risultati in modo che siano di un determinato tipo o di tipi principali passando il parametro includedPrimaryTypes.

    Utilizza questo parametro per specificare fino a cinque valori di tipo nella Tabella A o nella Tabella B. Un luogo deve corrispondere a uno dei valori di tipo primario specificati per essere incluso nella risposta.

    La richiesta viene rifiutata con un errore INVALID_REQUEST se:

    • Sono stati specificati più di cinque tipi.
    • Vengono specificati i tipi non riconosciuti.

  • includeQueryPredictions

    Se true, la risposta include sia le previsioni relative al luogo sia alle previsioni delle query. Il valore predefinito è false, il che significa che la risposta include solo le previsioni dei luoghi.

  • includedRegionCodes

    Includi solo i risultati dall'elenco delle regioni specificate, specificate come array di massimo 15 valori di due caratteri ccTLD ("dominio di primo livello"). Se omesso, non vengono applicate limitazioni alla risposta. Ad esempio, per limitare le regioni a Germania e Francia:

        "includedRegionCodes": ["de", "fr"]

    Se specifichi sia locationRestriction sia includedRegionCodes, i risultati si trovano nell'area di intersezione delle due impostazioni.

  • inputOffset

    L'offset di caratteri Unicode in base zero che indica la posizione del cursore in input. La posizione del cursore può influire sulle previsioni che vengono restituite. Se è vuoto, il valore predefinito è input.

  • languageCode

    La lingua preferita in cui restituire i risultati. I risultati potrebbero essere in lingue miste se la lingua utilizzata in input è diversa dal valore specificato da languageCode o se il luogo restituito non ha una traduzione dalla lingua locale in languageCode.

    • Devi utilizzare i codici lingua IETF BCP-47 per specificare la lingua preferita.
    • Se languageCode non viene fornito, l'API utilizza il valore specificato nell'intestazione Accept-Language. Se nessuno dei due è specificato, il valore predefinito è en. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
    • La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Questo influisce anche sulla capacità dell'API di correggere gli errori ortografici.
    • L'API tenta di fornire un indirizzo che sia leggibile sia per l'utente che per la popolazione locale, rispecchiando allo stesso tempo l'input dell'utente. Le previsioni dei luoghi sono formattate in modo diverso a seconda dell'input utente in ciascuna richiesta.
      • I termini corrispondenti nel parametro input vengono scelti per primi, utilizzando nomi allineati alla preferenza di lingua indicata dal parametro languageCode se disponibile, altrimenti utilizzando i nomi che corrispondono meglio all'input utente.
      • Gli indirizzi sono formattati nella lingua locale, in uno script leggibile dall'utente quando possibile, solo dopo che i termini corrispondenti sono stati selezionati in modo che corrispondano a quelli del parametro input.
      • Tutti gli altri indirizzi vengono restituiti nella lingua preferita dopo che i termini corrispondenti sono stati scelti in modo che corrispondano ai termini del parametro input. Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.

  • posizioneBias o limitazione di località

    Puoi specificare locationBias o locationRestriction, ma non entrambi, per definire l'area di ricerca. Pensa a locationRestriction come a specificare la regione in cui devono trovarsi i risultati, mentre locationBias a specifica la regione in cui i risultati devono essere vicini, ma che possono essere al di fuori dell'area.

    • locationBias

      Specifica un'area da cercare. Questa località funge da bias, il che significa che possono essere restituiti i risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata.

    • locationRestriction

      Specifica un'area da cercare. I risultati al di fuori dell'area specificata non vengono restituiti.

    Specifica la regione locationBias o locationRestriction come area visibile rettangolare o come cerchio.

    • Un cerchio viene definito dal punto centrale e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,0 inclusi. Il valore predefinito è 0,0. Per locationRestriction, devi impostare il raggio su un valore maggiore di 0,0. In caso contrario, la richiesta non restituisce alcun risultato.

      Ad esempio:

      "locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

    • Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due diagonali opposti a low e ai punti alti. Un'area visibile è considerata una regione chiusa, ovvero include i suoi confini. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi, mentre i limiti di longitudine devono essere compresi tra -180 e 180 gradi inclusi:

      • Se low = high, l'area visibile è composta da quel singolo punto.
      • Se low.longitude > high.longitude, l'intervallo di longitudine viene invertito (l'area visibile attraversa la linea di longitudine di 180 gradi).
      • Se low.longitude = -180 gradi e high.longitude = 180 gradi, l'area visibile include tutte le longitudini.
      • Se low.longitude = 180 gradi e high.longitude = -180 gradi, l'intervallo di longitudine è vuoto.

      È necessario compilare entrambi i campi low e high e la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.

      Ad esempio, questa area visibile racchiude completamente New York City:

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • origine

    Il punto di origine da cui calcolare la distanza in linea retta dalla destinazione (restituito come distanceMeters). Se questo valore viene omesso, la distanza in linea retta non verrà restituita. Devono essere specificate come coordinate di latitudine e longitudine:

    "origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

  • regionCode

    Il codice regione utilizzato per formattare la risposta, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").

    Se specifichi un codice regione non valido, l'API restituisce un errore INVALID_ARGUMENT. Il parametro può influire sui risultati in base alla legge vigente.

  • sessionToken

    I token di sessione sono stringhe generate dall'utente che monitorano le chiamate di completamento automatico (nuovo) come "sessioni". Il completamento automatico (nuova) utilizza i token di sessione per raggruppare le fasi di query e selezione della ricerca con completamento automatico di un utente in una sessione discreta ai fini della fatturazione. Per maggiori informazioni, consulta la sezione Token sessione.

Esempi di completamento automatico (nuovi)

Usa limitazioni di località e locationBias

Per impostazione predefinita, l'API utilizza la differenziazione IP per controllare l'area di ricerca. Con la differenziazione IP, l'API utilizza l'indirizzo IP del dispositivo per polarizzare i risultati. Facoltativamente, puoi utilizzare locationRestriction o locationBias, ma non entrambi, per specificare un'area da cercare.

locationRestriction specifica l'area da cercare. I risultati al di fuori dell'area specificata non vengono restituiti. Nell'esempio seguente, utilizza locationRestriction per limitare la richiesta a un cerchio di 5000 metri con un raggio centrato su San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Tutti i risultati all'interno delle aree specificate sono contenuti nell'array suggestions:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

Con locationBias, la località funge da bias, il che significa che è possibile restituire i risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata. Nell'esempio successivo, modifichi la richiesta in modo che utilizzi locationBias:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

I risultati ora contengono molti più elementi, compresi quelli al di fuori del raggio di 5000 metri:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

Utilizzare inclusioni principali

Utilizza il parametro includedPrimaryTypes per limitare i risultati di una richiesta di un determinato tipo, come elencato nella Tabella A e nella Tabella B. Puoi specificare un array di massimo cinque valori. Se omesso, vengono restituiti tutti i tipi.

Nell'esempio seguente, specifichi una stringa input di "Calcio" e utilizzi il parametro includedPrimaryTypes per limitare i risultati alle fondazioni di tipo "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Se ometti il parametro includedPrimaryTypes, i risultati possono includere costruzioni di un tipo non desiderato, come "athletic_field".

Richiedi previsioni delle query

Per impostazione predefinita, non vengono restituite le previsioni delle query. Utilizza il parametro di richiesta includeQueryPredictions per aggiungere previsioni di query alla risposta. Ad esempio:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

L'array suggestions ora contiene sia le previsioni delle località sia le previsioni delle query, come mostrato sopra in Informazioni sulla risposta. Ogni previsione di query include il campo text contenente una stringa di ricerca testuale consigliata. Puoi effettuare una richiesta di ricerca testuale (nuova) per ottenere maggiori informazioni su una qualsiasi delle previsioni delle query restituite.

Utilizza origine

In questo esempio, includi nella richiesta origin come coordinate di latitudine e longitudine. Se includi origin, l'API include il campo distanceMeters nella risposta che contiene la distanza in linea retta da origin alla destinazione. Questo esempio imposta l'origine sul centro di San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

La risposta ora include distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}