Completamento automatico (novità)

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

Il servizio Autocomplete (New) può trovare corrispondenze con parole complete e sottostringhe dell'input, risolvendo i nomi dei luoghi, gli indirizzi plus code. Le applicazioni possono quindi inviare automaticamente durante la digitazione, per fornire previsioni immediate e sulle query.

La risposta dell'API Autocomplete (new) può contenere due tipi delle previsioni:

• Previsioni sui luoghi: luoghi, come attività, indirizzi e punti di l'interesse, in base alla stringa di testo di input e all'area di ricerca specificate. Le previsioni sui luoghi sono vengono restituiti per impostazione predefinita.
• Previsioni sulle query: stringhe di query corrispondenti alla stringa di testo di input e nell'area di ricerca. Le previsioni delle query non vengono restituite per impostazione predefinita. Utilizza la Parametro di richiesta includeQueryPredictions per aggiungere previsioni della query al la risposta corretta.

Ad esempio, chiami l'API utilizzando come input una stringa che contiene un input parziale dell'utente, "Sicilian piz", con l'area di ricerca limitata a San Francisco, California. La risposta contiene quindi elenco di previsioni dei luoghi che corrispondono alla stringa di ricerca e all'area di ricerca, come intitolato "Sicilian Pizza Kitchen", insieme a informazioni dettagliate sul luogo.

Le previsioni del luogo restituite sono progettate per essere presentate all'utente per aiutare selezionando il luogo desiderato. Puoi creare un Dettagli del luogo (novità) richiedere ulteriori informazioni sulle previsioni dei luoghi restituite.

La risposta può anche contenere un elenco di previsioni della query corrispondenti stringa di ricerca e area di ricerca, ad esempio "Pizza Siciliana & pasta". Ogni previsione della query nel la risposta include il campo text contenente una stringa di ricerca testuale consigliata. Usalo stringa come input Ricerca testuale (novità) per eseguire una ricerca più dettagliata.

Explorer API ti consente di effettuare richieste in tempo reale per familiarizzare con l'API e Opzioni API:

Prova!

Richieste di completamento automatico (nuove)

Una richiesta Autocomplete (Nuova) è una richiesta POST HTTP a un URL in il modulo:

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

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 percezione della loro pertinenza. Ogni luogo è rappresentato da un placePrediction campo e ogni query è rappresentata da un campo queryPrediction.
• Un campo placePrediction contiene informazioni dettagliate su una singola la previsione del luogo, inclusi l'ID luogo e la descrizione testuale.
• Un campo queryPrediction contiene informazioni dettagliate su una singola la previsione delle 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 plus code. Il servizio Autocomplete (nuovo) restituisce le corrispondenze dei candidati in base a questa stringa e ordina i risultati in base a la loro pertinenza percepita.

Parametri facoltativi

• includedPrimaryTypes

  Un luogo può avere un solo unico tipo principale tra i tipi elencati in Tabella A oppure 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 del valore del tipo principale associato al luogo. Limita i risultati a un determinato di tipo primario o di tipo primario passando il parametro includedPrimaryTypes.

  Utilizza questo parametro per specificare fino a cinque valori di tipo dalla Tabella A o Tabella B. Un luogo deve corrisponde a uno dei valori di tipo principale specificati da includere nella risposta.

  Questo parametro può anche includere, invece, uno dei seguenti valori: (regions) o (cities). La raccolta di tipi (regions) applica filtri per aree o divisioni, come quartieri e codici postali. La raccolta dei tipi di (cities) applica un filtro ai luoghi che Google identifica come città.

  La richiesta viene rifiutata con un errore INVALID_REQUEST se:

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

• includeQueryPredictions

  Se true, la risposta include previsioni sia sul luogo sia sulla query. Il valore predefinito è false, il che significa che la risposta include solo le previsioni sui luoghi.

• includedRegionCodes

  Includi solo i risultati dell'elenco di regioni specificate, specificate come un array di massimo 15 ccTLD ("dominio di primo livello") valori a 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 Unicode su base zero che indica la posizione del cursore in input. La posizione del cursore può influire sulle previsioni restituite. Se vuoto, viene utilizzato il valore predefinito lunghezza di input.

• languageCode

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

  • Devi utilizzare IETF Codici lingua BCP-47 per specificare la lingua preferita.
  • Se languageCode non viene specificato, l'API utilizza il valore specificato nel campo Intestazione Accept-Language. Se nessuno dei due è specificato, il valore predefinito è en. Se specifichi un codice lingua non valido, l'API restituisce un INVALID_ARGUMENT errore.
  • La lingua preferita ha una piccola influenza sull'insieme di risultati che che l'API sceglie di restituire e l'ordine in cui vengono restituiti. Ciò influisce anche sulla capacità dell'API di correggere gli errori ortografici.
  • L'API cerca di fornire un indirizzo stradale che sia leggibile sia per l'utente che per popolazione locale, riflettendo al contempo l'input dell'utente. Le previsioni sui luoghi sono formattati in modo diverso a seconda dell'input dell'utente in ciascuna richiesta.
    • I termini corrispondenti nel parametro input vengono scelti per primi e utilizzano i nomi allineati con la preferenza di lingua indicata dal parametro languageCode quando disponibili, utilizzando al contrario i nomi che meglio corrispondono all'input dell'utente.
    • Gli indirizzi vengono formattati nella lingua locale, in uno script leggibile dall'utente quando possibile, solo dopo aver scelto i termini corrispondenti ai termini Parametro input.
    • Tutti gli altri indirizzi vengono restituiti nella lingua preferita, dopo che i termini corrispondenti sono stati scelto in modo che corrisponda ai termini nel parametro input. Se il nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più simile.

• locationBias o locationRestriction

  Puoi specificare locationBias o locationRestriction, ma non entrambi, per definire l'area di ricerca. Considera locationRestriction come una specifica regione in cui devono trovarsi i risultati e locationBias che specifica la regione alla quale i risultati devono essere vicini, ma che possono essere al di fuori della zona.

  • locationBias

    Specifica un'area in cui eseguire la ricerca. Questa località funge da bias, che significa è possibile restituire 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 sono restituito.

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

  • Un cerchio viene definito dal centro e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50000,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 viene restituita nessun 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 diagonalmente opposta a low e punti più alti. Un'area visibile è considerata un regione chiusa, ovvero include il confine. I limiti di latitudine deve essere compreso tra -90 e 90 gradi inclusi e i limiti di longitudine deve essere compreso 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 è 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 vuoto. 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 alla destinazione (restituita come distanceMeters). Se questo valore è omessa, la distanza in linea retta non verrà restituita. Deve essere specificato come coordinate di latitudine e longitudine:

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

• regionCode

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

  Se specifichi un codice regione non valido, l'API restituisce un 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 il completamento automatico (Novità) chiamate come "sessioni". Il completamento automatico (novità) utilizza i token di sessione per le fasi di query e selezione di una ricerca con completamento automatico da parte di un utente in una sessione discreta per ai fini della fatturazione. Per ulteriori informazioni, vedi Token di sessione.

Esempi di completamento automatico (nuovi)

Utilizza locationRestriction e locationBias

L'API utilizza per impostazione predefinita la differenziazione IP per controllare l'area di ricerca. Con la differenziazione per IP, l'API utilizza Indirizzo IP del dispositivo per differenziazione dei risultati. Se vuoi, puoi utilizzare locationRestriction o locationBias, ma non entrambi, per specificare un'area in cui eseguire la ricerca.

locationRestriction specifica l'area in cui eseguire la ricerca. Risultati al di fuori dell'area specificata e non vengono restituiti. Nell'esempio seguente, viene utilizzato locationRestriction per limitare il richiesta a un cerchio di 5000 metri di 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, che indica che i risultati relativi a: è possibile restituire la posizione specificata, compresi i risultati al di fuori dell'area specificata. Nei prossimi Ad esempio, 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 altri elementi, inclusi i risultati 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"
        ]
      }
    },
    ...
  ]
}

Usa includiPrincipalType

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 di tipo primario da includere nella risposta.

Nell'esempio seguente, specifichi una stringa input di "Calcio" e utilizza il parametro includedPrimaryTypes per limitare i risultati a strutture 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 locali di un tipo che non vuoi, come "athletic_field".

Richiedi previsioni per le query

Le previsioni delle query non vengono restituite per impostazione predefinita. Usa includeQueryPredictions per aggiungere previsioni della 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. Previsione di ogni query include il campo text contenente una stringa di ricerca testuale consigliata. Puoi creare un Ricerca testuale (novità) per ottenere maggiori informazioni sulle previsioni delle query restituite.

Usa origine

In questo esempio, includi nella richiesta origin sotto forma di coordinate di latitudine e longitudine. Se includi origin, l'API include il campo distanceMeters nella risposta che contiene la distanza in linea retta tra origin alla destinazione. Questo esempio imposta l'origine in base 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
      }
    }
  ]
}

Prova

Explorer API ti consente di effettuare richieste di esempio di acquisire familiarità con le opzioni dell'API e delle API.

1. Seleziona l'icona dell'API . sul lato destro della pagina.
2. Se vuoi, espandi Mostra parametri standard e imposta il parametro fields alla maschera del campo.
3. Se vuoi, modifica il corpo della richiesta.
4. Seleziona il pulsante Esegui. Nella finestra popup, scegli l'account che vuoi utilizzare per effettuare la richiesta.

5. Nel riquadro Explorer API, seleziona l'icona Espandi, , per espandere la finestra Explorer API.