Yer Otomatik Tamamlama Veri API'sı

Place Autocomplete Data API, otomatik tamamlama widget'ıyla mümkün olandan daha hassas bir kontrol derecesiyle özelleştirilmiş otomatik tamamlama deneyimleri oluşturmak için yer tahminlerini programatik olarak getirmenizi sağlar. Bu kılavuzda, kullanıcı sorgularına göre otomatik tamamlama isteklerinde bulunmak için Place Autocomplete Data API'yi nasıl kullanacağınızı öğreneceksiniz.

Aşağıdaki örnekte basit bir type-ahead entegrasyonu gösterilmektedir. Arama sorgunuzu girin ve istediğiniz sonucu seçmek için tıklayın.

Otomatik Tamamlama istekleri

Otomatik tamamlama isteği, bir sorgu giriş dizesini alır ve yer tahminlerinin listesini döndürür. Otomatik tamamlama isteğinde bulunmak için fetchAutocompleteSuggestions() yöntemini çağırıp gerekli özellikleri içeren bir istek iletin. input özelliği, 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, istek gövdesinin oluşturulması ve oturum jetonu eklenmesi, ardından PlacePrediction öğelerinin listesini almak için fetchAutocompleteSuggestions() yönteminin ç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 sınırla

Otomatik Yer Tamamlama özelliği, varsayılan olarak kullanıcının konumuna yakın tahminlere göre tüm yer türlerini sunar ve kullanıcının seçtiği yere ait tüm kullanılabilir veri alanlarını getirir. Sonuçları kısıtlayarak veya onlara ağırlık vererek daha alakalı tahminler sunmak için Yer Otomatik Tamamlama seçeneklerini ayarlayın.

Sonuçları kısıtlamak, Otomatik Tamamlama widget'ının kısıtlama alanının dışındaki sonuçları yoksaymasına neden olur. Sonuçları harita sınırlarıyla sınırlamak yaygın bir uygulamadır. Sonuçlara ağırlık verme, 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 özelliğini kullanın. Bu değer atlanırsa mesafe döndürülmez.

En fazla beş yer türü belirtmek için includedPrimaryTypes özelliğini kullanın. Herhangi bir tür belirtilmezse her tür yer döndürülür.

API referansını inceleyin

Yer ayrıntılarını al

Bir yer tahmini sonucundan Place nesnesi döndürmek için önce toPlace() yöntemini çağırın, ardından elde edilen Place nesnesinde fetchFields() yöntemini çağırın (yer tahminindeki oturum kimliği otomatik olarak eklenir). fetchFields() çağrısı yapıldığında otomatik tamamlama oturumu sonlandırılı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ı, faturalandırma amacıyla bir kullanıcı otomatik tamamlama aramasının sorgu ve seçim aşamalarını 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ına çağrı yapıldığında oturum sona erer.

Yeni bir oturum jetonu oluşturmak ve bunu bir isteğe eklemek için AutocompleteSessionToken örneği oluşturun, ardından isteğin sessionToken özelliğini, jetonları aşağıdaki snippet'te gösterildiği gibi 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() çağrıldığında bir oturum sona erer. Place örneğini oluşturduktan sonra, oturum jetonunu fetchFields() hizmetine iletmeniz gerekmez. Bu işlem otomatik olarak yapılır. 

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

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

Yeni bir AutocompleteSessionToken örneği oluşturarak bir sonraki oturum için oturum jetonu oluşturun.

Oturum jetonu önerileri:

  • Tüm Otomatik Yer 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 oturum için kullanılması, her isteğin ayrı olarak faturalandırılır.

İsterseniz otomatik tamamlama oturum jetonunu isteğe çıkarabilirsiniz. Oturum jetonu atlanırsa her istek ayrı olarak faturalandırılır ve Otomatik tamamlama - İstek Başına SKU'sunu tetikler. Bir oturum jetonunu yeniden kullanırsanız oturum geçersiz olarak kabul edilir ve istekler, herhangi bir oturum jetonu sağlanmamış gibi ücretlendirilir.

Örnek

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

Uygulamalar açısından etkinlik akışı şu şekildedir:

  1. Bir kullanıcı "Paris, Fransa"yı aramak için bir sorgu yazmaya başlıyor.
  2. Kullanıcı girişi algılandıktan sonra uygulama, "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 karakter için potansiyel sonuçların yeni bir listesini gösterir:
    "P"
    "Par"
    "Paris,"
    "Paris, Cuma"
  4. Kullanıcı bir seçim yaptığında:
    • Sorgudan kaynaklanan tüm istekler gruplanır ve "A Jetonu" ile temsil edilen oturuma tek bir istek olarak eklenir.
    • Kullanıcının seçimi 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 siler.
Oturumların nasıl faturalandırıldığı hakkında bilgi edinin

Örnek kodu tamamlayın

Bu bölümde Yer Otomatik Tamamlama Veri API'sının nasıl kullanılacağını gösteren tam örnekler bulunmaktadır .

Otomatik tamamlama tahminleri yerleştirme

Aşağıdaki örnekte, "Tadi" girişi için fetchAutocompleteSuggestions() çağrısı, ardından ilk tahmin sonucunda toPlace() çağrısı ve ardından yer ayrıntılarını almak için 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

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

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

Otomatik tamamlama türünde, oturumlarla birlikte yazımı ileri yerleştir

Bu örnekte, kullanıcı sorgularına göre fetchAutocompleteSuggestions() çağrısı, yanıt olarak tahmin edilen yerlerin bir listesini ve son olarak da seçilen yerin yer ayrıntılarının alınması gösterilmektedir. Örnekte, bir kullanıcı sorgusunu son 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

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

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