Place Autocomplete Data API

Place Autocomplete Data API, otomatik tamamlama widget'ında mümkün olandan daha hassas bir kontrol düzeyiyle özelleştirilmiş otomatik tamamlama deneyimleri oluşturmak için yer tahminlerini programatik olarak almanıza olanak tanır. Bu kılavuzda, kullanıcı sorgularına göre otomatik tamamlama istekleri yapmak için Yer Adı Otomatik Tamamlama Veri API'sini nasıl kullanacağınızı öğreneceksiniz.

Aşağıdaki örnekte basit bir önceden yazma entegrasyonu gösterilmektedir. Arama sorgunuzu girin, ardından tıklayarak istediğiniz sonucu seçin.

Not: Otomatik Yer Tamamlama Veri API'sini harita olmadan da kullanabilirsiniz. Harita göstermeniz gerekiyorsa bu Google haritası olmalıdır. Otomatik tamamlama hizmetinden gelen tahminleri harita olmadan gösterdiğinizde, arama alanıyla/sonuçlarla satır içi olarak gösterilen Google logosunu eklemeniz gerekir. Daha fazla bilgi için Google logosunu ve ilişkilendirmelerini gösterme başlıklı makaleyi inceleyin.

Otomatik tamamlama istekleri

Otomatik tamamlama isteği, bir sorgu giriş dizesi alır ve yer tahminlerinin listesini döndürür. Otomatik tamamlama isteği yapmak için fetchAutocompleteSuggestions() işlevini çağırın ve gerekli özellikleri içeren bir istek gönderin. input mülkü, aranacak dizeyi içerir. Tipik bir uygulamada bu değer, kullanıcı sorgu yazarken güncellenir. İstek, faturalandırma amacıyla kullanılan bir sessionToken içermelidir.

Aşağıdaki snippet'te, bir istek gövdesi oluşturulması ve oturum jetonu eklenmesi, ardından PlacePrediction öğelerinin listesini almak için fetchAutocompleteSuggestions() çağrılması gösterilmektedir.

// 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

Otomatik Tamamlama tahminlerini kısıtlama

Varsayılan olarak Yer Otomatik Tamamlama, tüm yer türlerini kullanıcının konumuna yakın tahminler için önyargılı olarak sunar ve kullanıcının seçtiği yer için mevcut tüm veri alanlarını getirir. Sonuçları kısıtlayarak veya sonuçlara önyargı katarak daha alakalı tahminler sunmak için Yer Otomatik Tamamlama seçeneklerini ayarlayın.

Sonuçların kısıtlanması, Otomatik Tamamlama widget'ının kısıtlama alanının dışındaki tüm sonuçları yoksaymasına neden olur. Sonuçları harita sınırlarıyla kısıtlamak yaygın bir uygulamadır. Sonuçları önyargılı olarak belirlemek, Otomatik Tamamlama widget'ının belirtilen alandaki sonuçları göstermesini sağlar ancak bazı eşleşmeler bu alanın dışında olabilir.

Hedefe olan jeodezik mesafenin hesaplanacağı başlangıç noktasını belirtmek için origin mülkünü kullanın. Bu değer atlanırsa mesafe döndürülmez.

Beş adede kadar yer türünü belirtmek için includedPrimaryTypes mülkünü kullanın. Tür belirtilmezse tüm türlerdeki yerler döndürülür.

API referansına bakın

Yer ayrıntılarını alma

Bir yer tahmini sonucundan Place nesnesi döndürmek için önce toPlace(), ardından elde edilen Place nesnesinde fetchFields() işlevini çağırın (yer tahmininden alınan oturum kimliği otomatik olarak eklenir). fetchFields() çağrısı, otomatik tamamlama oturumunu sonlandırır.

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

Oturum jetonları

Oturum jetonları, kullanıcı otomatik tamamlama aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırır. Oturum, kullanıcı yazmaya başladığında başlar. Kullanıcı bir yer seçtiğinde ve Yer Ayrıntıları çağrısı yapıldığında oturum sona erer.

Yeni bir oturum jetonu oluşturup bir isteğe eklemek için AutocompleteSessionToken örneği oluşturun, ardından isteğin sessionToken mülkünü aşağıdaki snippet'te gösterildiği gibi jetonları kullanacak şekilde ayarlayın:

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

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

fetchFields() işlevi çağrıldığında oturum sona erer. Place örneğini oluşturduktan sonra oturum jetonunu fetchFields()'a iletmeniz gerekmez. Bu işlem otomatik olarak gerçekleştirilir.

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

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

AutocompleteSessionToken için yeni bir örnek oluşturarak bir sonraki oturum için oturum jetonu oluşturun.

Oturum jetonu önerileri:

• Tüm yer otomatik tamamlama çağrıları için oturum jetonları kullanın.
• Her oturum için yeni bir jeton oluşturun.
• Her yeni oturum için benzersiz bir oturum jetonu iletin. Aynı jetonun birden fazla oturumda kullanılması, her isteğinin ayrı olarak faturalandırılmasına neden olur.

İsteğe bağlı olarak otomatik tamamlama oturum jetonunu isteklerden çıkarabilirsiniz. Oturum jetonu atlanırsa her istek ayrı olarak faturalandırılır ve Otomatik Tamamlama - İstek Başına SKU'su tetiklenir. Bir oturum jetonunu yeniden kullanırsanız oturum geçersiz kabul edilir ve isteklerden oturum jetonu sağlanmamış gibi ücret alınır.

Örnek

Kullanıcı bir sorgu yazarken birkaç tuş vuruşunda bir otomatik tamamlama isteği çağrılır (karakter başına değil) ve olası sonuçların listesi döndürülür. Kullanıcı sonuç listesinden bir seçim yaptığında bu seçim bir istek olarak sayılır ve arama sırasında yapılan tüm istekler birleştirilerek tek bir istek olarak sayılır. Kullanıcı bir yer seçerse arama sorgusu ücretsizdir ve yalnızca yer verisi isteği ücretlendirilir. Kullanıcı, oturumun başlangıcından sonraki birkaç dakika içinde bir seçim yapmazsa yalnızca arama sorgusu için ödeme alınır.

Bir uygulamanın bakış açısından etkinlik akışı şöyledir:

1. Kullanıcı, "Paris, Fransa" araması yapmak için bir sorgu yazmaya başlar.
2. Uygulama, kullanıcı girişini algıladıktan sonra "A jetonu" adlı yeni bir oturum jetonu oluşturur.
3. Kullanıcı yazarken API birkaç karakterde bir otomatik tamamlama isteği gönderir ve her biri için olası sonuçların yeni bir listesini gösterir:
   "P"
   "Par"
   "Paris,"
   "Paris, Fr"
   
4. Kullanıcı bir seçim yaptığında:
   • Sorgudan kaynaklanan tüm istekler gruplandırılır ve "A jetonu" ile temsil edilen oturuma tek bir istek olarak eklenir.
   • Kullanıcının seçimi bir yer ayrıntısı isteği olarak sayılır ve "A jetonu" ile temsil edilen oturuma eklenir.
5. Oturum sona erer ve uygulama "A jetonu"nu atar.

Oturumların nasıl faturalandırıldığı hakkında bilgi edinin.

Eksiksiz örnek kod

Bu bölümde, Place Autocomplete Data API'nin nasıl kullanılacağını gösteren eksiksiz örnekler yer almaktadır .

Yer otomatik tamamlama tahminleri

Aşağıdaki örnekte, "Tadi" girişi için fetchAutocompleteSuggestions() çağrısı, ardından ilk tahmin sonucu için toPlace() çağrısı ve ardından yer ayrıntılarını almak üzere fetchFields() çağrısı gösterilmektedir.

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

Not: TypeScript ve Google Haritalar'ı kullanmayla ilgili kılavuzu okuyun.

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

Not: JavaScript, TypeScript snippet'inden derlenir.

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

Örneği Deneyin

JSFiddle.net Google Cloud Shell

Oturumlarla yer otomatik tamamlama önizlemesi

Bu örnekte, kullanıcı sorgularına göre fetchAutocompleteSuggestions() çağrısı yapılması, yanıt olarak tahmin edilen yerlerin listesi gösterilmesi ve son olarak seçilen yerle ilgili yer ayrıntılarının alınması gösterilmektedir. Örnekte, bir kullanıcı sorgusunu nihai Yer Ayrıntıları isteğiyle gruplandırmak için oturum jetonlarının kullanımı da gösterilmektedir.

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

Not: TypeScript ve Google Haritalar'ı kullanmayla ilgili kılavuzu okuyun.

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

Not: JavaScript, TypeScript snippet'inden derlenir.

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

Örneği Deneyin

JSFiddle.net Google Cloud Shell