Interfejs Place Autocomplete Data API

Interfejs Place Autocomplete Data API umożliwia pobieranie prognoz miejsc automatycznie tworzyć niestandardowe funkcje autouzupełniania z większą kontrolą niż jest to możliwe dzięki widżetowi autouzupełniania. Z tego przewodnika dowiesz się, jak korzystać z Umieść interfejs API danych autouzupełniania, aby wysyłać żądania autouzupełniania na podstawie informacji o użytkowniku zapytań.

Poniżej znajduje się przykład prostej integracji pisania z wyprzedzeniem. Wpisz zapytanie i kliknij aby wybrać interesujący Cię wynik.

Uwaga: możesz używać interfejsu Place Autocomplete Data API nawet bez mapy. Jeśli jest wyświetlana mapa, musi to być mapa Google. W przypadku wyświetlania podpowiedzi z usługi autouzupełniania bez mapy, należy dołączyć logo Google wyświetlane w tekście pola wyszukiwania/wyników. Więcej informacji: Wyświetlanie logo Google i informacji o źródłach.

Żądania autouzupełniania

Żądanie autouzupełniania pobiera ciąg wejściowy zapytania i zwraca listę prognoz dotyczących miejsc. Do wykonaj żądanie autouzupełniania, zadzwoń pod numer fetchAutocompleteSuggestions() i przekazać żądanie z wymaganymi właściwościami. input właściwość zawiera ciąg do wyszukania; w typowej aplikacji wartość ta zostałaby zaktualizowana jako użytkownik wpisuje zapytanie. Prośba powinna zawierać sessionToken, który służy do rozliczeń.

Ten fragment kodu przedstawia tworzenie treści żądania i dodawanie tokena sesji, a następnie wywołanie fetchAutocompleteSuggestions(), aby uzyskać listę: PlacePrediction

// Add an initial request body.
let request = {
  input: "Tadi",
  locationRestriction: {
    west: -122.44,
    north: 37.8,
    east: -122.39,
    south: 37.78,
  },
  origin: { lat: 37.7893, lng: -122.4039 },
  includedPrimaryTypes: ["restaurant"],
  language: "en-US",
  region: "us",
};
// Create a session token.
const token = new AutocompleteSessionToken();

// Add the token to the request.
// @ts-ignore
request.sessionToken = token;
index.js

Ogranicz podpowiedzi autouzupełniania

Domyślnie autouzupełnianie miejsc przedstawia wszystkie typy miejsc, a ponadto pokazuje podpowiedzi w pobliżu i pobiera wszystkie dostępne pola danych dotyczące wybranego miejsca. Ustaw miejsce Opcje autouzupełniania pozwalające wyświetlać trafniejsze podpowiedzi przez ograniczanie lub promowanie wyników.

Ograniczenie wyników powoduje, że widżet autouzupełniania ignoruje wszystkie wyniki, które nie znajdują się objęte ograniczeniami. Zalecaną praktyką jest ograniczanie wyników do granic mapy. Wyniki promowania sprawia, że widżet autouzupełniania wyświetla wyniki z określonego obszaru, ale niektóre dopasowania mogą być poza nią.

Użyj właściwości origin do określenia punktu początkowego, z którego ma zostać obliczony punkt początkowy odległość geodezyjna do miejsca docelowego. Jeśli ta wartość zostanie pominięta, odległość nie jest zwracana.

Korzystanie z includedPrimaryTypes możesz określić maksymalnie 5 typów miejsc. Jeśli nie podasz żadnych typów, zwrócone zostaną miejsca wszystkich typów.

Zobacz dokumentację interfejsu API

Pobierz informacje o miejscu

Aby zwrócić Place obiekt z wyniku prognozy miejsca, pierwsze wywołanie toPlace(), potem zadzwoń do: fetchFields() w wynikowym obiekcie Place (identyfikator sesji z prognozy dotyczącej miejsca jest dołączany automatycznie). Połączenie z użytkownikiem fetchFields() zakończy .

let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.

await place.fetchFields({
  fields: ["displayName", "formattedAddress"],
});

const placeInfo = document.getElementById("prediction");

placeInfo.textContent =
  "First predicted place: " +
  place.displayName +
  ": " +
  place.formattedAddress;
index.js

Tokeny sesji

Tokeny sesji grupują fazy zapytania i wyboru wyszukiwania autouzupełniania użytkownika w dyskretną sesję do celów rozliczeniowych. Sesja rozpoczyna się, gdy użytkownik zaczyna pisać. Sesja kończy się, gdy użytkownik wybierze miejsce i nawiązane jest połączenie z informacjami o miejscu.

Aby utworzyć nowy token sesji i dodać go do żądania, utwórz instancję AutocompleteSessionToken następnie ustaw sessionToken do żądania użycia tokenów, jak pokazano w tym fragmencie:

// Create a session token.
const token = new AutocompleteSessionToken();

// Add the token to the request.
// @ts-ignore
request.sessionToken = token;
index.js

Sesja kończy się, gdy fetchFields() . Po utworzeniu instancji Place nie musisz zaliczać sesji. do fetchFields(), ponieważ jest on obsługiwany automatycznie.

await place.fetchFields({
  fields: ["displayName", "formattedAddress"],
});
index.js

await place.fetchFields({
    fields: ['displayName'],
  });

Aby utworzyć token sesji dla następnej sesji, utwórz nowe wystąpienie AutocompleteSessionToken.

Rekomendacje dotyczące tokena sesji:

• Używaj tokenów sesji dla wszystkich wywołań autouzupełniania miejsc.
• Wygeneruj nowy token dla każdej sesji.
• Dla każdej nowej sesji przekaż unikalny token sesji. Używanie tego samego tokena w więcej niż jednej sesji co spowoduje rozliczenie każdego żądania osobno.

Opcjonalnie możesz pominąć token sesji autouzupełniania w żądaniu. Jeśli token sesji to pomijane, każde żądanie jest rozliczane osobno, co aktywuje Autouzupełnianie – według żądań SKU. Jeśli ponownie użyjesz tokena sesji, sesja zostanie uznana za nieważną i za żądania zostaną naliczone opłaty tak, jakby nie podano tokena sesji.

Przykład

Gdy użytkownik wpisuje zapytanie, żądanie autouzupełniania jest wywoływane co kilka razy. naciśnięć klawiszy (nie poszczególnych znaków) i zwracana jest lista możliwych wyników. Gdy użytkownik dokona wyboru z listy wyników, jest on liczony jako i wszystkie żądania zgłaszane podczas wyszukiwania są grupowane liczone jako pojedyncze żądanie. Jeśli użytkownik wybierze miejsce, zapytanie będzie dostępne bezpłatnie, a opłata zostanie naliczona tylko za żądanie danych dotyczących miejsca. Jeśli użytkownik nie wykona można ją zaznaczyć na kilka minut przed rozpoczęciem sesji, naliczana jest opłata za wyszukiwane hasło.

Przebieg zdarzeń z perspektywy aplikacji wygląda tak:

1. Użytkownik zaczyna wpisywać zapytanie, aby wyszukać „Paryż, Francja”.
2. Po wykryciu danych wejściowych użytkownika aplikacja tworzy nową sesję „Token A”.
3. Gdy użytkownik wpisuje tekst, interfejs API wysyła żądanie autouzupełniania co kilka znaków, wyświetlająca nową listę potencjalnych wyników dla każdego z tych elementów:
   „O”
   „Par”
   „Paryż”,
   „Paryż, pt”
   
4. Gdy użytkownik dokona wyboru:
   • Wszystkie żądania wynikające z zapytania są grupowane i dodawane do sekcji reprezentowana przez „Token A” jako pojedyncze żądanie.
   • Wybór użytkownika jest liczony jako żądanie szczegółowych informacji o miejscu i dodany, sesji reprezentowanej przez „Token A”.
5. Sesja dobiega końca, a aplikacja odrzuca „Token A”.

. Więcej informacji o opłatach za sesje

Uzupełnij przykładowy kod

Ta sekcja zawiera pełne przykłady korzystania z interfejsu Place Autocomplete Data API .

Umieszczaj podpowiedzi autouzupełniania

Poniższy przykład pokazuje, jak wywoływać funkcję fetchAutocompleteSuggestions() dla danych wejściowych „tadi”, a następnie wywołaj toPlace() na pierwszym wyniku prognozy, a następnie wywołanie funkcji fetchFields() w celu uzyskania szczegółowych informacji o miejscu.

TypeScript

/**
 * Demonstrates making a single request for Place predictions, then requests Place Details for the first result.
 */
async function init() {
    // @ts-ignore
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = await google.maps.importLibrary("places") as google.maps.PlacesLibrary;

    // Add an initial request body.
    let request = {
        input: "Tadi",
        locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78 },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ["restaurant"],
        language: "en-US",
        region: "us",
    };

    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    const title = document.getElementById('title') as HTMLElement;
    title.appendChild(document.createTextNode('Query predictions for "' + request.input + '":'));

    for (let suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a new list element.
        const listItem = document.createElement('li');
        const resultsElement = document.getElementById("results") as HTMLElement;
        listItem.appendChild(document.createTextNode(placePrediction.text.toString()));
        resultsElement.appendChild(listItem);
    }

    let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });

    const placeInfo = document.getElementById("prediction") as HTMLElement;
    placeInfo.textContent = 'First predicted place: ' + place.displayName + ': ' + place.formattedAddress;

}

init();
index.ts

. Uwaga: przeczytaj przewodnik po korzystaniu z TypeScript i Map Google.

JavaScript

/**
 * Demonstrates making a single request for Place predictions, then requests Place Details for the first result.
 */
async function init() {
  // @ts-ignore
  const { Place, AutocompleteSessionToken, AutocompleteSuggestion } =
    await google.maps.importLibrary("places");
  // Add an initial request body.
  let request = {
    input: "Tadi",
    locationRestriction: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
    origin: { lat: 37.7893, lng: -122.4039 },
    includedPrimaryTypes: ["restaurant"],
    language: "en-US",
    region: "us",
  };
  // Create a session token.
  const token = new AutocompleteSessionToken();

  // Add the token to the request.
  // @ts-ignore
  request.sessionToken = token;

  // Fetch autocomplete suggestions.
  const { suggestions } =
    await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
  const title = document.getElementById("title");

  title.appendChild(
    document.createTextNode('Query predictions for "' + request.input + '":'),
  );

  for (let suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    // Create a new list element.
    const listItem = document.createElement("li");
    const resultsElement = document.getElementById("results");

    listItem.appendChild(
      document.createTextNode(placePrediction.text.toString()),
    );
    resultsElement.appendChild(listItem);
  }

  let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.

  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  const placeInfo = document.getElementById("prediction");

  placeInfo.textContent =
    "First predicted place: " +
    place.displayName +
    ": " +
    place.formattedAddress;
}

init();
index.js

. Uwaga: JavaScript jest kompilowany z fragmentu kodu TypeScript.

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}
style.css

HTML

<html>
  <head>
    <title>Place Autocomplete Data API Predictions</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="title"></div>
    <ul id="results"></ul>
    <p><span id="prediction"></span></p>
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html

Zobacz próbkę

JSFiddle.net Google Cloud Shell,

Wstawiaj autouzupełnianie z wyprzedzeniem do wpisywania sesji

Ten przykład pokazuje, fetchAutocompleteSuggestions() na podstawie zapytań użytkowników, wyświetlających listę przewidywanych miejsc w odpowiedzi oraz na końcu pobierania szczegóły wybranego miejsca. Ten przykład pokazuje też wykorzystanie tokenów sesji do pogrupować zapytanie użytkownika z ostatecznym żądaniem dotyczącym informacji o miejscu.

TypeScript

let title;
let results;
let input;
let token;

// Add an initial request body.
let request = {
    input: "",
    locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78 },
    origin: { lat: 37.7893, lng: -122.4039 },
    includedPrimaryTypes: ["restaurant"],
    language: "en-US",
    region: "us",
};

async function init() {
    token = new google.maps.places.AutocompleteSessionToken();

    title = document.getElementById('title');
    results = document.getElementById('results');
    input = document.querySelector("input");
    input.addEventListener("input", makeAcRequest);
    request = refreshToken(request) as any;
}

async function makeAcRequest(input) {
    // Reset elements and exit if an empty string is received.
    if (input.target.value == '') {
        title.innerText = '';
        results.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = input.target.value;

    // Fetch autocomplete suggestions and show them in a list.
    // @ts-ignore
    const { suggestions } = await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    title.innerText = 'Query predictions for "' + request.input + '"';

    // Clear the list first.
    results.replaceChildren();

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a link for the place, add an event handler to fetch the place.
        const a = document.createElement('a');
        a.addEventListener('click', () => {
            onPlaceSelected(placePrediction!.toPlace());
        });
        a.innerText = placePrediction!.text.toString();

        // Create a new list element.
        const li = document.createElement('li');
        li.appendChild(a);
        results.appendChild(li);
    }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });
    let placeText = document.createTextNode(place.displayName + ': ' + place.formattedAddress);
    results.replaceChildren(placeText);
    title.innerText = 'Selected Place:';
    input.value = '';
    refreshToken(request);
}

// Helper function to refresh the session token.
async function refreshToken(request) {
    // Create a new session token and add it to the request.
    token = new google.maps.places.AutocompleteSessionToken();
    request.sessionToken = token;
    return request;
}

declare global {
    interface Window {
      init: () => void;
    }
  }
  window.init = init;
index.ts

. Uwaga: przeczytaj przewodnik po korzystaniu z TypeScript i Map Google.

JavaScript

let title;
let results;
let input;
let token;
// Add an initial request body.
let request = {
  input: "",
  locationRestriction: {
    west: -122.44,
    north: 37.8,
    east: -122.39,
    south: 37.78,
  },
  origin: { lat: 37.7893, lng: -122.4039 },
  includedPrimaryTypes: ["restaurant"],
  language: "en-US",
  region: "us",
};

async function init() {
  token = new google.maps.places.AutocompleteSessionToken();
  title = document.getElementById("title");
  results = document.getElementById("results");
  input = document.querySelector("input");
  input.addEventListener("input", makeAcRequest);
  request = refreshToken(request);
}

async function makeAcRequest(input) {
  // Reset elements and exit if an empty string is received.
  if (input.target.value == "") {
    title.innerText = "";
    results.replaceChildren();
    return;
  }

  // Add the latest char sequence to the request.
  request.input = input.target.value;

  // Fetch autocomplete suggestions and show them in a list.
  // @ts-ignore
  const { suggestions } =
    await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(
      request,
    );

  title.innerText = 'Query predictions for "' + request.input + '"';
  // Clear the list first.
  results.replaceChildren();

  for (const suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    // Create a link for the place, add an event handler to fetch the place.
    const a = document.createElement("a");

    a.addEventListener("click", () => {
      onPlaceSelected(placePrediction.toPlace());
    });
    a.innerText = placePrediction.text.toString();

    // Create a new list element.
    const li = document.createElement("li");

    li.appendChild(a);
    results.appendChild(li);
  }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  let placeText = document.createTextNode(
    place.displayName + ": " + place.formattedAddress,
  );

  results.replaceChildren(placeText);
  title.innerText = "Selected Place:";
  input.value = "";
  refreshToken(request);
}

// Helper function to refresh the session token.
async function refreshToken(request) {
  // Create a new session token and add it to the request.
  token = new google.maps.places.AutocompleteSessionToken();
  request.sessionToken = token;
  return request;
}

window.init = init;
index.js

. Uwaga: JavaScript jest kompilowany z fragmentu kodu TypeScript.

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

a {
  cursor: pointer;
  text-decoration: underline;
  color: blue;
}

input {
  width: 300px;
}
style.css

HTML

<html>
  <head>
    <title>Place Autocomplete Data API Session</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <input id="input" type="text" placeholder="Search for a place..." />
    <div id="title"></div>
    <ul id="results"></ul>
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=init&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Zobacz próbkę

JSFiddle.net Google Cloud Shell,