Completamento automatico (novità)

Introduzione

Autocomplete (New) è un servizio web che restituisce previsioni relative ai luoghi e alle query in risposta a una richiesta HTTP. Nella richiesta, specifica una stringa di ricerca testuale e i confini geografici che controllano l'area di ricerca.

Autocomplete (New) può trovare corrispondenze con parole intere e sottostringhe dell'input, risolvendo nomi di luoghi, indirizzi e plus code. Le applicazioni possono quindi inviare query mentre l'utente digita, per fornire previsioni di luoghi e query in tempo reale.

La risposta di 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 di query: stringhe di query corrispondenti alla stringa di testo di input e all'area di ricerca. Le previsioni delle query non vengono restituite per impostazione predefinita. Utilizza il parametro di richiesta includeQueryPredictions per aggiungere previsioni di query alla risposta.

Ad esempio, chiami Autocomplete (New) utilizzando come input una stringa che contiene un input utente parziale, "Sicilian piz", con l'area di ricerca limitata a San Francisco, CA. La risposta contiene quindi un elenco di previsioni di luoghi che corrispondono alla stringa di ricerca e all'area di ricerca, ad esempio il ristorante denominato "Sicilian Pizza Kitchen", insieme ai dettagli del luogo.

Le previsioni dei luoghi restituite sono progettate per essere presentate all'utente per aiutarlo a selezionare il luogo previsto. Puoi effettuare una richiesta Place Details (New) per ottenere ulteriori informazioni su una qualsiasi delle previsioni dei luoghi restituite.

La risposta può anche contenere un elenco di previsioni di query che corrispondono alla stringa di ricerca e all'area di ricerca, ad esempio "Sicilian Pizza & Pasta". Ogni previsione di query nella risposta include il campo text contenente una stringa di ricerca di testo consigliata. Utilizza questa stringa come input per Ricerca testuale (nuova) per eseguire una ricerca più dettagliata.

Explorer API ti consente di effettuare richieste in tempo reale per acquisire familiarità con l'API e le relative opzioni:

Richieste Autocomplete (New)

Una richiesta Autocomplete (New) è una richiesta POST HTTP a un URL nel seguente 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

Parametri supportati

Informazioni sulla risposta

Autocomplete (New) 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 su una singola previsione di luogo, inclusi l'ID luogo e la descrizione testuale.
  • Per corrispondere più da vicino all'input dell'utente fornito nel parametro input, la descrizione testuale di una previsione di luogo può includere nomi alternativi per luoghi, strade e altri componenti dell'indirizzo. Questi nomi alternativi possono essere diversi da quelli restituiti nei campi displayName e indirizzo dei risultati di Place Details per lo stesso ID luogo.
  • In questo contesto, i nomi alternativi di alcuni luoghi potrebbero essere in una lingua diversa da quella prevista in base al parametro languageCode, a seconda dei nomi che corrispondono più da vicino all'input dell'utente.
• 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 cercare. Specifica parole intere e sottostringhe, nomi di luoghi, indirizzi e plus code. Il servizio Autocomplete (New) restituisce corrispondenze candidate in base a questa stringa e ordina i risultati in base alla loro pertinenza percepita.

Parametri facoltativi

FieldMask

Specifica l'elenco di campi da restituire nella risposta creando una maschera di campo della risposta. Passa la maschera di campo della risposta al metodo utilizzando l'intestazione HTTP X-Goog-FieldMask.

Specifica un elenco separato da virgole di campi di suggerimento da restituire. Ad esempio, per recuperare suggestions.placePrediction.text.text e suggestions.queryPrediction.text.text del suggerimento.

  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

Utilizza * per recuperare tutti i campi.

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

Se true, restituisce le attività che dovrebbero aprire in futuro. Il valore predefinito è false.

includedPrimaryTypes

Un luogo può avere un solo tipo principale tra quelli elencati nella Tabella A o nella Tabella B. Ad esempio, il tipo principale potrebbe essere "mexican_restaurant" o "steak_house".

Per impostazione predefinita, l'API restituisce tutti i luoghi in base al parametro input, indipendentemente dal valore del tipo principale associato al luogo. Limita i risultati a un determinato tipo principale o a determinati tipi principali passando il parametro includedPrimaryTypes.

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

Questo parametro può anche includere, in alternativa, uno dei valori (regions) o (cities). La raccolta di tipi (regions) filtra per aree o divisioni, come quartieri e codici postali. La raccolta di tipi (cities) filtra i luoghi che Google identifica come città.

La richiesta viene rifiutata con un errore INVALID_REQUEST se:

• Sono stati specificati più di cinque tipi.
• Viene specificato un tipo qualsiasi oltre a (cities) o (regions).
• Vengono specificati tutti i tipi non riconosciuti.

includePureServiceAreaBusinesses

Se impostato su true, la risposta include le attività che visitano o consegnano direttamente ai clienti, ma non hanno una sede fisica. Se impostata su false, l'API restituisce solo le attività con una sede fisica.

includeQueryPredictions

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

includedRegionCodes

Includi solo i risultati dell'elenco delle regioni specificate, indicate come un 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 alla Germania e alla Francia:

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

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

inputOffset

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

languageCode

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

• Per specificare la lingua preferita, devi utilizzare i codici lingua IETF BCP-47.
• Se languageCode non viene fornito, l'API utilizza il valore specificato nell'intestazione Accept-Language. Se non viene specificato nessuno dei due, 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. Ciò influisce anche sulla capacità dell'API di correggere gli errori ortografici.
• Le previsioni dei luoghi vengono formattate in modo diverso a seconda dell'input dell'utente in ogni richiesta.
  • I termini corrispondenti nel parametro input vengono scelti per primi, utilizzando i nomi allineati alla preferenza sulla lingua indicata dal parametro languageCode, se disponibile, altrimenti utilizzando i nomi che corrispondono meglio all'input dell'utente.
  • I nomi dei luoghi possono essere formattati utilizzando nomi alternativi per corrispondere ai termini nel parametro input, inclusi i nomi in lingue diverse da quella indicata dal parametro languageCode.
  • Gli indirizzi sono formattati nella lingua locale, in uno script leggibile dall'utente, se possibile, solo dopo che i termini corrispondenti sono stati scelti per corrispondere ai termini nel parametro input.
  • Tutti gli altri indirizzi vengono restituiti nella lingua preferita, dopo che sono stati scelti i termini corrispondenti a quelli nel parametro input. Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.

locationBias o locationRestriction

Per definire l'area di ricerca, puoi specificare locationBias o locationRestriction, ma non entrambi. Pensa a locationRestriction come alla regione in cui devono trovarsi i risultati e a locationBias come alla regione a cui i risultati devono essere vicini, ma possono trovarsi al di fuori dell'area.

• locationBias

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

• locationRestriction

  Specifica un'area in cui eseguire la ricerca. 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 è 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 risultati.

  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 punti low e alto diagonalmente opposti. Un'area visibile è considerata una regione chiusa, il che significa che include il suo confine. 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 è costituita da quel singolo punto.
  • Se low.longitude > high.longitude, l'intervallo di longitudine è 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.

  Sia low che high devono essere compilati 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 partenza da cui calcolare la distanza in linea retta fino alla destinazione (restituita come distanceMeters). Se questo valore viene omesso, la distanza in linea retta non verrà restituita. Deve essere specificata 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 suo codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").

I suggerimenti sono inoltre influenzati dai codici regione. Google consiglia di impostare regionCode in base alle preferenze locali dell'utente.

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.

Quando imposti regionCode, le previsioni all'interno di quella regione potrebbero omettere il nome del paese dal testo del suggerimento, il che significa che structuredFormat.secondaryText potrebbe non essere presente. Pertanto, assicurati che la tua applicazione gestisca i casi in cui secondaryText non è definito o manca.

sessionToken

I token di sessione sono stringhe generate dall'utente che monitorano le chiamate di Autocomplete (New) come "sessioni". Autocomplete (New) utilizza i token di sessione per raggruppare le fasi di query e selezione di una ricerca con completamento automatico dell'utente in una sessione distinta ai fini della fatturazione. Per saperne di più, consulta Token di sessione.

Scegli i parametri per influenzare i risultati

Esempi di Autocomplete (New)

Limita la ricerca a un'area utilizzando locationRestriction

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

curl -X POST -d '{
  "input": "Art museum",
  "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/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

Puoi anche utilizzare locationRestriction per limitare le ricerche a un viewport rettangolare. L'esempio seguente limita la richiesta al centro di San Francisco:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

I risultati sono contenuti nell'array suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

Personalizza la ricerca in un'area utilizzando locationBias

Con locationBias, la località funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata. Nell'esempio seguente, la richiesta viene indirizzata al centro di San Francisco:

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, inclusi 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"
        ]
      }
    },
    ...
  ]
}

Puoi anche utilizzare locationBias per influenzare le ricerche in un viewport rettangolare. L'esempio seguente limita la richiesta al centro di San Francisco:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Sebbene i risultati di ricerca all'interno dell'area visibile rettangolare vengano visualizzati nella risposta, alcuni risultati non rientrano nei confini definiti a causa della priorità. I risultati sono contenuti anche 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": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "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": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

Utilizza includedPrimaryTypes

Utilizza il parametro includedPrimaryTypes per specificare fino a cinque valori di tipo dalla Tabella A, dalla Tabella B o solo (regions) o solo (cities). Un luogo deve corrispondere a uno dei valori del tipo principale specificati per essere incluso nella risposta.

Nell'esempio seguente, specifichi una stringa input "Calcio" e utilizzi il parametro includedPrimaryTypes per limitare i risultati alle attività 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 attività di un tipo che non vuoi, ad esempio "athletic_field".

Richiedi previsioni delle query

Le previsioni delle query non vengono restituite per impostazione predefinita. Utilizza il parametro di richiesta includeQueryPredictions per aggiungere le 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 dei luoghi sia quelle 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 ulteriori informazioni su una qualsiasi delle previsioni di query restituite.

Usa origine

In questo esempio, includi origin nella richiesta come coordinate di latitudine e longitudine. Quando includi origin, Autocomplete (New) 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
      }
    }
  ]
}

Trova le attività che apriranno in futuro

L'esempio seguente mostra una richiesta di Autocomplete (New) per le attività che apriranno in futuro a New Meadows, Idaho:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

La risposta include i dettagli del luogo, ma non la data di apertura.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

Distanza mancante nella risposta

In alcuni casi, distanceMeters non è presente nel corpo della risposta, anche se origin è incluso nella richiesta. Questo è possibile nei seguenti scenari:

• distanceMeters non è incluso per le previsioni di route.
• distanceMeters non viene incluso quando il suo valore è 0, come nel caso di previsioni a meno di 1 metro di distanza dalla località origin fornita.

Le librerie client che tentano di leggere il campo distanceMeters da un oggetto analizzato restituiranno un campo con valore 0. Per evitare di indurre in errore gli utenti, non mostrare una distanza pari a zero.

Ottimizzazione del completamento automatico (nuovo)

Questa sezione descrive le best practice per aiutarti a sfruttare al meglio il servizio Autocomplete (New).

Ecco alcune linee guida generali:

• Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget di completamento automatico (nuovo) dell'API Maps JavaScript, il widget di completamento automatico (nuovo) di Places SDK for Android o il widget di completamento automatico (nuovo) di Places SDK for iOS.
• Comprendi i campi di dati essenziali di Autocomplete (New) fin dall'inizio.
• I campi di polarizzazione e limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
• Utilizza la gestione degli errori per assicurarti che l'app si degradi correttamente se l'API restituisce un errore.
• Assicurati che la tua app gestisca i casi in cui non viene effettuata alcuna selezione e offra agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione dei costi di base

Per ottimizzare il costo di utilizzo del servizio Autocomplete (New), utilizza le maschere di campo nei widget Place Details (New) e Autocomplete (New) per restituire solo i campi di dati di Autocomplete (New) di cui hai bisogno.

Ottimizzazione avanzata dei costi

Valuta l'implementazione programmatica di Autocomplete (New) per accedere allo SKU: Autocomplete Request pricing e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details (New). I prezzi per richiesta abbinati all'API Geocoding sono più convenienti dei prezzi per sessione (basati sulla sessione) se sono soddisfatte entrambe le seguenti condizioni:

• Se hai bisogno solo della latitudine e della longitudine o dell'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni a un costo inferiore rispetto a una chiamata di Place Details (New).
• Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro o meno richieste di previsioni di completamento automatico (nuovo), i prezzi per richiesta possono essere più convenienti rispetto ai prezzi per sessione.

L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details (New) per la tua applicazione, a seconda delle prestazioni di utilizzo di Autocomplete (New). L'efficienza di Autocomplete (New) di ogni applicazione varia a seconda di ciò che gli utenti inseriscono, di dove viene utilizzata l'applicazione e se sono state implementate le best practice per l'ottimizzazione delle prestazioni.

Per trovare il numero medio di richieste per la tabella, analizza quanti caratteri un utente digita in media prima di selezionare una previsione di Autocomplete (New) nella tua applicazione.

Autocomplete (New) basato su sessione con Place Details (New)

Utilizza Autocomplete (New) basato su sessione con Place Details (New).
Poiché la tua applicazione richiede Place Details (New), come il nome del luogo, lo stato dell'attività o l'orario di apertura, l'implementazione di Autocomplete (New) deve utilizzare un token di sessione (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per sessione, oltre agli SKU di Places applicabili, a seconda dei campi di dati dei luoghi richiesti.¹

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Autocomplete (New) sia la richiesta Place Details (New) sulla previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi di dati di Autocomplete (New) di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le tue richieste Autocomplete (New). Quando richiedi i dettagli dei luoghi (nuova versione) relativi alla previsione selezionata, includi i seguenti parametri:

1. L'ID luogo della risposta di Autocomplete (New)
2. Il token di sessione utilizzato nella richiesta Autocomplete (New)
3. Il parametro fields che specifica i campi di dati di Autocomplete (New) di cui hai bisogno

Autocomplete (New) per richiesta con l'API Geocoding

Implementa Autocomplete (New) in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione di luogo selezionata.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine. L'esecuzione di quattro richieste Autocomplete Requests più una chiamata all'API Geocoding relativa alla previsione del luogo selezionato è inferiore al costo per sessione di Autocomplete (New).¹

Valuta la possibilità di adottare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con un numero ancora minore di caratteri.

Autocomplete (New) basato su sessione per applicazioni solo per indirizzi

Utilizza Autocomplete (New) basato su sessione con Place Details (New).
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione di Autocomplete (New) supera il costo dei prezzi per sessione, la tua implementazione di Autocomplete (New) deve utilizzare un token di sessione sia per le richieste di Autocomplete (New) sia per la richiesta Place Details (New) associata per sessione. ¹

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Autocomplete (New) sia la richiesta Place Details (New) sulla previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le richieste Autocomplete (New). Quando richiedi i dettagli dei luoghi (nuova versione) relativi alla previsione selezionata, includi i seguenti parametri:

1. L'ID luogo della risposta di Autocomplete (New)
2. Il token di sessione utilizzato nella richiesta Autocomplete (New)
3. Il parametro fields che specifica i campi, ad esempio indirizzo e geometria

Valuta la possibilità di ritardare le richieste di Autocomplete (New)
Puoi adottare strategie come ritardare una richiesta di Autocomplete (New) finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che l'applicazione effettui meno richieste. Ad esempio, se effettui richieste di Autocomplete (New) per ogni carattere dopo che l'utente ha digitato il terzo carattere, se l'utente digita sette caratteri e poi seleziona una previsione per la quale effettui una richiesta API Geocoding, il costo totale sarà di 4 richieste Autocomplete (New) Per Request + Geocoding.¹

Se ritardando le richieste puoi ridurre la media delle richieste programmatiche a meno di quattro, puoi seguire le indicazioni per l'implementazione di Autocomplete (New) con l'API Geocoding. Tieni presente che il ritardo delle richieste può essere percepito come latenza dall'utente, che potrebbe aspettarsi di vedere le previsioni a ogni nuova pressione di un tasto.

Valuta la possibilità di adottare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che stanno cercando con meno caratteri.

Best practice per le prestazioni

Le seguenti linee guida descrivono i modi per ottimizzare le prestazioni di Autocomplete (New):

• Aggiungi limitazioni in base al paese, localizzazione e (per le implementazioni programmatiche) preferenza sulla lingua alla tua implementazione di Autocomplete (New). La preferenza sulla lingua non è necessaria con i widget, poiché questi ultimi scelgono le preferenze sulla lingua dal browser o dal dispositivo mobile dell'utente.
• Se Autocomplete (New) è accompagnato da una mappa, puoi influenzare la località in base all'area visibile della mappa.
• In situazioni in cui un utente non sceglie una delle previsioni di Autocomplete (New), in genere perché nessuna di queste previsioni è l'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per tentare di ottenere risultati più pertinenti:
  • Se prevedi che l'utente inserisca solo informazioni sull'indirizzo, riutilizza l'input utente originale in una chiamata all'API Geocoding.
  • Se prevedi che l'utente inserisca query per un luogo specifico in base al nome o all'indirizzo, utilizza una richiesta Place Details (New). Se i risultati sono previsti solo in una regione specifica, utilizza la localizzazione.
  Altri scenari in cui è meglio utilizzare l'API Geocoding includono:
  • Utenti che inseriscono indirizzi di unità secondarie, ad esempio indirizzi di unità o appartamenti specifici all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praga" restituisce una previsione parziale in Autocomplete (New).
  • Utenti che inseriscono indirizzi con prefissi di segmenti stradali come "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.

Bias di località

Per orientare i risultati verso un'area specifica, passa un parametro location e un parametro radius. In questo modo, Autocomplete (New) preferisce mostrare i risultati all'interno dell'area definita. Potrebbero comunque essere visualizzati risultati al di fuori dell'area definita. Puoi utilizzare il parametro includedRegionCodes per filtrare i risultati in modo da mostrare solo i luoghi all'interno di un paese specificato.

Limitazione della località

Limita i risultati a un'area specificata passando un parametro locationRestriction.

Puoi anche limitare i risultati alla regione definita da location e da un parametro radius aggiungendo il parametro locationRestriction . In questo modo, Autocomplete (New) restituisce solo i risultati all'interno di quella regione.

Prova

Explorer API ti consente di effettuare richieste di esempio per acquisire familiarità con l'API e le relative opzioni.

1. Seleziona l'icona dell'API api sul lato destro della pagina.

2. Se vuoi, modifica i parametri della richiesta.

3. Seleziona il pulsante Esegui. Nella finestra di dialogo, scegli l'account che vuoi utilizzare per effettuare la richiesta.

4. Nel riquadro Explorer API, seleziona l'icona Schermo intero fullscreen per espandere la finestra di Explorer API.