Completamento automatico (novità)

Introduzione

Completamento automatico (nuovo) è un servizio web che restituisce previsioni di luoghi e query in risposta a una richiesta HTTP. Nella richiesta, specifica una stringa di ricerca di testo e i limiti geografici che controllano l'area di ricerca.

Il completamento automatico (nuovo) 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 al volo.

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

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

Ad esempio, chiami Autocomplete (New) utilizzando come input una stringa che contiene 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, ad esempio il ristorante chiamato "Sicilian Pizza Kitchen", insieme ai dettagli sul luogo.

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

La risposta può contenere anche 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 di testo (nuova) per eseguire una ricerca più dettagliata.

L'Explorer API ti consente di effettuare richieste in tempo reale per familiarizzare con l'API e le relative opzioni:

Richieste Autocomplete (New)

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

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

Trasmetti tutti i parametri nel corpo della richiesta JSON o nelle intestazioni nell'ambito 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

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 da un campo queryPrediction.
• Un campo placePrediction contiene informazioni dettagliate su una singola previsione del luogo, 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

• immissione

  La stringa di testo su cui eseguire la ricerca. 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 dei campi da restituire nella risposta creando una maschera del campo di risposta. Passa la maschera del campo di risposta al metodo utilizzando l'intestazione HTTP X-Goog-FieldMask.

  Specifica un elenco separato da virgole dei 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: *

• 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 tipi principali passando il parametro includedPrimaryTypes.

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

  Questo parametro può includere anche (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 in aggiunta a (cities) o (regions).
  • Vengono specificati tutti i tipi non riconosciuti.

• includePureServiceAreaBusinesses

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

• includeQueryPredictions

  Se true, la risposta include sia le previsioni di luogo che di 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 array di massimo 15 ccTLD ("top-level domain") valori di due caratteri. 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 del carattere Unicode in base 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 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 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.
  • L'API tenta di fornire un indirizzo stradale leggibile sia per l'utente sia per la popolazione locale, riflettendo al contempo l'input dell'utente. 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 nomi in linea con la preferenza di lingua indicata dal parametro languageCode quando disponibile, altrimenti utilizzando nomi che corrispondono meglio all'input dell'utente.
    • Gli indirizzi stradali sono formattati nella lingua locale, in un sistema di scrittura leggibile dall'utente quando possibile, solo dopo che sono stati selezionati i termini corrispondenti per corrispondere 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 nel parametro input. Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.

• locationBias o locationRestriction

  Puoi specificare locationBias o locationRestriction, ma non entrambi, per definire l'area di ricerca. Considera locationRestriction come la regione in cui devono trovarsi i risultati e locationBias come la regione in cui devono trovarsi i risultati, ma possono essere al di fuori dell'area.

  • locationBias

    Specifica un'area in cui cercare. Questa posizione funge da bias, il che significa che possono essere restituiti risultati intorno alla posizione specificata, inclusi risultati al di fuori dell'area specificata.

  • locationRestriction

    Specifica un'area in cui 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 è 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 punti low e alto diagonalmente opposti. Un viewport è considerato una regione chiusa, il che significa che include il suo confine. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi e i limiti di longitudine devono essere compresi tra -180 e 180 gradi inclusi:

    • Se low = high, l'area visibile è costituita da un 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 finestra completamente racchiude 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 fino alla destinazione (restituita 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 ("top-level domain"). La maggior parte dei codici ccTLD sono identici ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il TLD specifico per paese 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 anche influenzati dai codici regione. Google consiglia di impostare regionCode in base alle preferenze regionali 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.

• sessionToken

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

Scegli i parametri per distorcere i risultati

Esempi di completamento automatico (nuovo)

Limitare la ricerca a un'area utilizzando locationRestriction

locationRestriction specifica l'area in cui cercare. I risultati al di fuori dell'area specificata non vengono restituiti. Nell'esempio seguente, utilizzi locationRestriction per limitare la richiesta a un cerchio di 5000 metri di raggio 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 provenienti dalle 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'area visibile 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"
          ]
        }
      }
    ]
  }

Orientare la ricerca verso un'area utilizzando locationBias

Con locationBias, la posizione funge da bias, il che significa che possono essere restituiti risultati intorno alla posizione specificata, inclusi risultati al di fuori dell'area specificata. Nell'esempio che segue, la richiesta è orientata 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 orientare le ricerche verso una finestra 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 del riquadro rettangolare vengano visualizzati nella risposta, alcuni risultati si trovano al di fuori dei limiti definiti a causa della distorsione. 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 da Tabella A, 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 di "Calcio" e utilizzi il parametro includedPrimaryTypes per limitare i risultati agli stabilimenti 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 ti interessa, ad esempio "athletic_field".

Richiedere le previsioni delle query

Le previsioni delle query non vengono restituite per impostazione predefinita. Utilizza il parametro di richiesta includeQueryPredictions per aggiungere le previsioni delle 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 le previsioni delle query, come mostrato sopra in Informazioni sulla risposta. Ogni previsione di query include il campo text contenente una stringa di ricerca di testo consigliata. Puoi effettuare una richiesta di Ricerca di testo (nuova) per ottenere maggiori informazioni su una qualsiasi delle previsioni di query restituite.

Utilizza origine

In questo esempio, includi origin nella richiesta come coordinate di latitudine e longitudine. Quando includi origin, il completamento automatico (nuovo) include il campo distanceMeters nella risposta, che contiene la distanza in linea retta da origin alla destinazione. Questo esempio imposta l'origine al 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
      }
    }
  ]
}

Distanza mancante nella risposta

In alcuni casi, distanceMeters non è presente nel corpo della risposta, anche quando origin è incluso nella richiesta. Ciò può verificarsi nei seguenti scenari:

• distanceMeters non è incluso nelle previsioni di route.
• distanceMeters non è incluso quando il suo valore è 0, come nel caso delle previsioni che si trovano a meno di 1 metro di distanza dalla posizione 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 ingannare gli utenti, non mostrare una distanza pari a zero agli utenti.

Ottimizzazione del completamento automatico (novità)

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 per il completamento automatico (novità) fin dall'inizio.
• I campi di preferenza della località e di limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
• Utilizza la gestione degli errori per assicurarti che la tua app funzioni correttamente se l'API restituisce un errore.
• Assicurati che la tua app gestisca i casi in cui non è presente alcuna selezione e offra agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione di base dei costi

Per ottimizzare il costo dell'utilizzo del servizio Autocomplete (New), utilizza le maschere dei campi 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 sul luogo selezionato anziché su Places Details (New). Il prezzo per richiesta abbinato all'API Geocoding è più conveniente del prezzo per sessione (basato sulla sessione) se sono soddisfatte entrambe le seguenti condizioni:

• Se hai bisogno solo della latitudine/longitudine o dell'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni a un costo inferiore rispetto a una chiamata a Place Details (New).
• Se gli utenti selezionano un suggerimento di completamento automatico entro una media di quattro o meno richieste di completamento automatico (nuovo), il prezzo per richiesta potrebbe essere più conveniente rispetto al prezzo per sessione.

La tua applicazione richiede informazioni diverse dall'indirizzo e dalla latitudine/longitudine della previsione selezionata?

Best practice per le prestazioni

Le seguenti linee guida descrivono i modi per ottimizzare il rendimento del completamento automatico (nuovo):

• Aggiungi limitazioni per paese, bias di località, e (per le implementazioni programmatiche) preferenza della lingua all'implementazione di Completamento automatico (nuovo). La preferenza della lingua non è necessaria con i widget, poiché questi scelgono le preferenze della lingua dal browser o dal dispositivo mobile dell'utente.
• Se il completamento automatico (nuovo) è accompagnato da una mappa, puoi impostare la località in base alla visualizzazione della mappa.
• Nelle situazioni in cui un utente non sceglie una delle previsioni di completamento automatico (nuovo), 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 Dettagli luogo (nuovo). Se i risultati sono previsti solo in una regione specifica, utilizza la priorità della località.
  Altri scenari in cui è meglio ricorrere all'API Geocoding includono:
  • Gli 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, Praha" restituisce una previsione parziale in Autocomplete (New).
  • Gli 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 nelle Hawaii.

Bias di località

Inclina i risultati verso un'area specificata passando un parametro location e un parametro radius. In questo modo, il completamento automatico (nuovo) preferisce mostrare i risultati all'interno dell'area definita. I risultati al di fuori dell'area definita potrebbero comunque essere visualizzati. Puoi utilizzare il parametro components per filtrare i risultati in modo da mostrare solo i luoghi all'interno di un paese specifico.

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

L'Explorer API ti consente di effettuare richieste di esempio per familiarizzare con l'API e le relative opzioni.

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

2. (Facoltativo) 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 a schermo intero fullscreen per espandere la finestra di Explorer API.