Yer Otomatik Tamamlama Veri API'sı

Place Autocomplete Data API, otomatik tamamlama widget'ına kıyasla daha hassas bir kontrolle özelleştirilmiş otomatik tamamlama deneyimleri oluşturmak için yer tahminlerini programlı bir şekilde getirmenize olanak tanır. 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, ardından istediğiniz sonucu seçmek için tıklayın.

Not: Place Autocomplete Data API'yi harita olmadan bile kullanabilirsiniz. Harita gösteriyorsanız bu bir Google haritası olmalıdır. Otomatik tamamlama hizmetinden gelen tahminleri harita olmadan görüntülediğinizde, arama alanına/sonuçlarına satır içinde gösterilen Google logosunu eklemeniz gerekir. Daha fazla bilgi için Google logosunu ve ilişkilendirmeleri görüntüleme konusuna bakın.

Otomatik Tamamlama istekleri

Otomatik tamamlama isteği, bir sorgu giriş dizesini alır ve yer tahminlerinin bir listesini döndürür. Otomatik tamamlama isteğinde bulunmak için fetchAutocompleteSuggestions() öğesini çağırın ve gerekli özelliklerle birlikte bir istek iletin. input özelliği aranacak dizeyi içerir. Normal bir uygulamada bu değer, kullanıcı bir sorgu yazarken güncellenir. İstek, faturalandırma amacıyla kullanılan bir sessionToken içermelidir.

Aşağıdaki snippet'te istek gövdesi oluşturma ve oturum jetonu ekleme, ardından PlacePrediction listesini almak için fetchAutocompleteSuggestions() çağrısı yapma 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, varsayılan olarak kullanıcının konumuna yakın tahminler için eğilimli olarak tüm yer türlerini sunar ve kullanıcının seçtiği yer için kullanılabilir tüm veri alanlarını getirir. Sonuçları kısıtlayarak veya sonuçlara 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ışında kalan sonuçları yoksaymasına neden olur. Sonuçların harita sınırlarıyla sınırlandırılması sık başvurulan bir uygulamadır. Sonuçlara ağırlık verme Otomatik Tamamlama widget'ının belirtilen alan içindeki sonuçları göstermesini sağlar, ancak bazı eşleşmeler bu alanın dışında da 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. Hiçbir tür belirtilmezse, her türden yer döndürülür.

API referansına bakın

Yer ayrıntılarını alın

Bir yer tahmini sonucundan bir Place nesnesi döndürmek için ilk olarak toPlace() yöntemini, ardından elde edilen Place nesnesinde fetchFields() yöntemini çağırın (yer tahminindeki oturum kimliği otomatik olarak dahil edilir). fetchFields() çağrı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ı, bir 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ı için bir arama yapıldığında oturum sona erer.

Yeni bir oturum jetonu oluşturup 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 sonlandırılır. 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ını 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ğin ayrı ayrı faturalandırılmasına neden olur.

Dilerseniz otomatik tamamlama oturum jetonunu bir istekten çı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 sayılır ve istekler için oturum jetonu sağlanmamış gibi ücret alınır.

Örnek

Kullanıcı bir sorguyu yazarken, her birkaç tuş vuruşunda bir (karakter başına değil) bir otomatik tamamlama isteği çağrılır ve olası sonuçların bir 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 gruplanarak tek bir istek olarak sayılır. Kullanıcı bir yer seçerse arama sorgusu ücretsiz olarak kullanılabilir ve yalnızca Yer verileri isteği için ücret alınır. Kullanıcı, oturumun başlamasından sonraki birkaç dakika içinde bir seçim yapmazsa yalnızca arama sorgusu için ücret alınır.

Uygulamalar açısından bakıldığında etkinlik akışı aşağıdaki gibidir:

1. Bir kullanıcı "Paris, Fransa"yı aramak için bir sorgu yazmaya başlar.
2. Kullanıcı girişi algılandığında uygulama, "A Jetonu" adlı yeni bir oturum jetonu oluşturur.
3. API, kullanıcı yazı yazarken her birkaç karakter için bir otomatik tamamlama isteği göndererek her biri için yeni bir potansiyel sonuç listesi 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 bir Yer Ayrıntısı isteği olarak sayılır ve "Jeton A" 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 eksiksiz örnekler yer almaktadır .

Yer otomatik tamamlama tahminleri

Aşağıdaki örnekte, "Tadi" girişi için fetchAutocompleteSuggestions(), ardından ilk tahmin sonucunda toPlace() ve yer ayrıntılarını almak için fetchFields() çağrısının çağrılması 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'ın kullanımıyla 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>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 otomatik tamamlamayı önceden yazın

Bu örnekte, kullanıcı sorgularına göre fetchAutocompleteSuggestions() çağrısı yapılması, yanıt olarak tahmin edilen yerlerin listesinin gösterilmesi ve son olarak seçilen yer için yer ayrıntılarının alınması gösterilmektedir. Örnekte, bir kullanıcı sorgusunu son Yer Ayrıntısı 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'ın kullanımıyla 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>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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