Place Autocomplete Data API

Avrupa Ekonomik Alanı'ndaki (AEA) geliştiriciler

Fatura adresiniz Avrupa Ekonomik Alanı'ndaysa 8 Temmuz 2025'ten itibaren Hizmetleri kullanımınız Google Haritalar Platformu AEA Hizmet Şartları'na tabi olacaktır. İşlevler bölgeye göre değişir. Daha fazla bilgi edinin.

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

Aşağıdaki örnekte, basitleştirilmiş bir önceden yazma entegrasyonu gösterilmektedir. "Pizza" veya "poke" gibi bir arama sorgusu girin, ardından istediğiniz sonucu tıklayarak seçin.

Otomatik tamamlama istekleri

Otomatik tamamlama isteği, bir sorgu giriş dizesi alır ve yer tahminlerinin listesini döndürür. Otomatik tamamlama isteğinde bulunmak için fetchAutocompleteSuggestions() yöntemini çağırın ve gerekli özelliklere sahip bir istek iletin. input özelliği, aranacak dizeyi içerir. Tipik bir uygulamada bu değer, kullanıcı bir sorgu yazdıkça 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() yöntemini çağırma işlemi gösterilmektedir.

// Add an initial request body.
const 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.
request.sessionToken = token;
index.js

Otomatik tamamlama tahminlerini kısıtlama

Yer Adı Otomatik Tamamlama, varsayılan olarak tüm yer türlerini sunar, kullanıcının konumuna yakın tahminlere öncelik verir 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 ağırlık vererek daha alakalı tahminler sunmak için Yer Adı 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ı yok saymasına neden olur. Sonuçları harita sınırlarıyla kısıtlamak yaygın bir uygulamadır. Sonuçları yönlendirme, 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 tüm türlerdeki yerler döndürülür.

API referansını inceleyin

Yer ayrıntılarını alma

Bir yer tahmini sonucundan Place nesnesi döndürmek için önce toPlace() yöntemini, ardından sonuçta elde edilen Place nesnesinde fetchFields() yöntemini çağırın (yer tahminindeki oturum kimliği otomatik olarak dahil edilir). fetchFields() çağrısı, otomatik tamamlama oturumunu sonlandırır.

const 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ının 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ı çağrısı yapıldığında oturum sona erer.

Yeni bir oturum jetonu oluşturup isteğe eklemek için AutocompleteSessionToken örneği oluşturun, ardından isteğin sessionToken özelliğini 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.
request.sessionToken = token;
index.js

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

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

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

Oturum jetonu önerileri

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

İsterseniz otomatik tamamlama oturum jetonunu istekten çıkarabilirsiniz. Oturum jetonu atlanırsa her istek ayrı olarak faturalandırılır ve Autocomplete - Per Request SKU'su tetiklenir. Bir oturum jetonunu yeniden kullanırsanız oturum geçersiz sayılır ve istekler, oturum jetonu sağlanmamış gibi ücretlendirilir.

Örnek

Kullanıcı bir sorgu yazarken her birkaç tuş vuruşunda bir (karakter başına değil) otomatik tamamlama isteği çağrılır 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 bir araya getirilerek 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 ücretlendirilir. Kullanıcı, oturumun başlamasından sonraki birkaç dakika içinde seçim yapmazsa yalnızca arama sorgusu için ücret alınır.

Bir uygulama açısından etkinlik akışı şu şekildedir:

1. Kullanıcı, "Paris, Fransa"yı aramak için bir sorgu yazmaya başlar.
2. Uygulama, kullanıcı girişini algıladığında yeni bir oturum jetonu ("Jeton A") oluşturur.
3. Kullanıcı yazarken API, her birkaç karakterde bir otomatik tamamlama isteği göndererek her biri için yeni bir potansiyel sonuç listesi gösterir:
   "P"
   "Par"
   "Paris,"
   "Paris, Fr"
   
4. Kullanıcı 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, Yer Ayrıntıları isteği olarak sayılır ve "A Jetonu" ile temsil edilen oturuma eklenir.
5. Oturum sona erer ve uygulama "A jetonunu" siler.

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

Eksiksiz örnek kod

Bu bölümde, Yer Adı Otomatik Tamamlama Data API'nin nasıl kullanılacağını gösteren eksiksiz örnekler yer alır.

Yer adı otomatik tamamlama tahminleri

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

TypeScript

async function init() {
    const { AutocompleteSessionToken, AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    // Add an initial request body.
    const request: google.maps.places.AutocompleteRequest = {
        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.
    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 + '":'
        )
    );

    const resultsElement = document.getElementById('results')!;

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

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

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

    const 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}`;
}

void init();
index.ts

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

JavaScript

async function init() {
    const { AutocompleteSessionToken, AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    // Add an initial request body.
    const 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.
    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 + '":'
        )
    );

    const resultsElement = document.getElementById('results');

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

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

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

    const 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}`;
}

void 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>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <div id="title"></div>
        <ul id="results"></ul>
        <p><span id="prediction"></span></p>
        <img
            class="powered-by-google"
            src="./powered_by_google_on_white.png"
            alt="Powered by Google" />
    </body>
</html>
index.html

Oturumlarla yer adı otomatik tamamlama

Bu örnekte aşağıdaki kavramlar gösterilmektedir:

• Kullanıcı sorgularına göre fetchAutocompleteSuggestions() yöntemini çağırır ve yanıt olarak tahmini yerlerin listesini gösterir.
• Kullanıcı sorgusunu nihai Yer Ayrıntıları isteğiyle gruplandırmak için oturum jetonlarını kullanma
• Seçilen yerin ayrıntılarını alma ve işaretçi gösterme
• gmp-map öğesindeki kullanıcı arayüzü öğelerini iç içe yerleştirmek için denetim konumlandırma kullanılıyor.

TypeScript

const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
const titleElement = document.querySelector<HTMLElement>('.title')!;
const resultsContainerElement = document.querySelector('.results')!;
const inputElement = document.querySelector('input')!;
const tokenStatusElement = document.querySelector('.token-status')!;
let newestRequestId = 0;
let tokenCount = 0;

// Create an initial request body.
const request: google.maps.places.AutocompleteRequest = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};

async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Update request center and bounds when the map bounds change.
    innerMap.addListener('bounds_changed', () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });

    inputElement.addEventListener('input', makeAutocompleteRequest);
}

async function makeAutocompleteRequest(inputEvent: Event) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;

    const { AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    if (!(inputEvent.target as HTMLInputElement)?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = (inputEvent.target as HTMLInputElement).value;

    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId) return;

    titleElement.innerText = `Place predictions for "${request.input}"`;

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

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

        if (!placePrediction) {
            continue;
        }

        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            void onPlaceSelected(placePrediction.toPlace());
        });

        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');

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

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place: google.maps.places.Place) {
    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

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

    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';

    await refreshToken();

    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }

    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });

    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}

// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } =
        await google.maps.importLibrary('places');

    // Increment the token counter.
    tokenCount++;

    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}

void init();
index.ts

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

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;
let marker;
const titleElement = document.querySelector('.title');
const resultsContainerElement = document.querySelector('.results');
const inputElement = document.querySelector('input');
const tokenStatusElement = document.querySelector('.token-status');
let newestRequestId = 0;
let tokenCount = 0;

// Create an initial request body.
const request = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};

async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Update request center and bounds when the map bounds change.
    innerMap.addListener('bounds_changed', () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });

    inputElement.addEventListener('input', makeAutocompleteRequest);
}

async function makeAutocompleteRequest(inputEvent) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;

    const { AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    if (!inputEvent.target?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }

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

    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId) return;

    titleElement.innerText = `Place predictions for "${request.input}"`;

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

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

        if (!placePrediction) {
            continue;
        }

        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            void onPlaceSelected(placePrediction.toPlace());
        });

        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');

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

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

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

    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';

    await refreshToken();

    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }

    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });

    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}

// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } =
        await google.maps.importLibrary('places');

    // Increment the token counter.
    tokenCount++;

    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}

void init();
index.js

CSS

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

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

.place-button {
    height: 3rem;
    width: 100%;
    background-color: transparent;
    text-align: left;
    border: none;
    cursor: pointer;
}

.place-button:focus-visible {
    outline: 2px solid #0056b3;
    border-radius: 2px;
}

.input {
    width: 300px;
    font-size: small;
    margin-bottom: 1rem;
}

/* Styles for the floating panel */
.controls {
    background-color: #fff;
    border-radius: 8px;
    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
    font-family: sans-serif;
    font-size: small;
    margin: 12px;
    padding: 1rem;
}

.title {
    font-weight: bold;
    margin-top: 1rem;
    margin-bottom: 0.5rem;
}

.results {
    list-style-type: none;
    margin: 0;
    padding: 0;
}

.results li:not(:last-child) {
    border-bottom: 1px solid #ddd;
}

.results li:hover {
    background-color: #eee;
}
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>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <gmp-map center="37.7893, -122.4039" zoom="12" map-id="DEMO_MAP_ID">
            <div class="controls" slot="control-inline-start-block-start">
                <input
                    type="text"
                    class="input"
                    placeholder="Search for a place..."
                    autocomplete="off" /><!-- Turn off the input's own autocomplete (not supported by all browsers).-->
                <div class="token-status"></div>
                <div class="title"></div>
                <ol class="results"></ol>
            </div>
        </gmp-map>
    </body>
</html>
index.html

Otomatik tamamlama (yeni) optimizasyonu

Bu bölümde, Otomatik Tamamlama (Yeni) hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.

Genel kurallardan bazıları şunlardır:

• Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu, Maps JavaScript API Otomatik Tamamlama (Yeni) widget'ını, Android için Yerler SDK'sı Otomatik Tamamlama (Yeni) widget'ını veya iOS için Yerler SDK'sı Otomatik Tamamlama (Yeni) widget'ını kullanmaktır.
• Temel Otomatik Tamamlama (Yeni) veri alanlarını en baştan anlayın.
• Konum tercihi ve konum kısıtlama alanları isteğe bağlıdır ancak otomatik tamamlama performansı üzerinde önemli bir etkiye sahip olabilir.
• API bir hata döndürürse uygulamanızın düzgün bir şekilde çalışmaya devam etmesi için hata işleme özelliğini kullanın.
• Uygulamanızın, seçim yapılmadığında bu durumu ele aldığından ve kullanıcılara devam etme yolu sunduğundan emin olun.

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Autocomplete (New) hizmetini kullanma maliyetini optimize etmek için Yer Ayrıntıları (New) ve Autocomplete (New) widget'larında alan maskeleri kullanarak yalnızca ihtiyacınız olan Autocomplete (New) veri alanlarını döndürün.

Gelişmiş maliyet optimizasyonu

SKU: Autocomplete Request fiyatlandırmasına erişmek ve Yer Ayrıntıları (Yeni) yerine seçilen yerle ilgili Geocoding API sonuçları istemek için Autocomplete'in (Yeni) programatik uygulamasını kullanabilirsiniz. Geocoding API ile eşlenen istek başına fiyatlandırma, aşağıdaki koşulların her ikisi de karşılandığında oturum başına (oturum tabanlı) fiyatlandırmadan daha uygun maliyetlidir:

• Yalnızca kullanıcının seçtiği yerin enlem ve boylamına veya adresine ihtiyacınız varsa Geocoding API, bu bilgileri Yer Ayrıntıları (Yeni) çağrısından daha düşük bir ücret karşılığında sağlar.
• Kullanıcılar, ortalama dört veya daha az Otomatik Tamamlama (Yeni) tahmin isteği içinde bir otomatik tamamlama tahmini seçerse istek başına fiyatlandırma, oturum başına fiyatlandırmadan daha uygun maliyetli olabilir.

Uygulamanız için en düşük maliyetli Autocomplete (New) uygulamasını seçmek üzere aşağıdaki tabloda uygulamanızın ihtiyaçlarına uygun satırı bulun.

Uygulamanızın ihtiyaç duyduğu izinler	Kullanıcı bir tahmin seçmeden önce ortalama Otomatik Tamamlama (Yeni) isteği sayısı	Önerilen uygulama
Adres ve konum dışındaki yer ayrıntıları (ör. yer adı, işletme durumu veya çalışma saatleri)	Herhangi bir sayıda	Yer Ayrıntıları (Yeni) ile oturum tabanlı Otomatik Tamamlama (Yeni)
Yalnızca seçilen tahminin adresi ve enlem/boylamı	Dört veya daha az	Geocoding API ile istek başına Autocomplete (New)
Yalnızca seçilen tahminin adresi ve enlem/boylamı	Dörtten fazla	Yalnızca adres uygulamaları için oturum tabanlı Autocomplete (New)

Geocoding API, Autocomplete (New) kullanımınızın performansına bağlı olarak uygulamanız için Yer Ayrıntıları (New)'dan daha uygun maliyetli bir seçenek olabilir. Her uygulamanın Autocomplete (New) verimliliği; kullanıcıların ne girdiğine, uygulamanın nerede kullanıldığına ve performans optimizasyonuyla ilgili en iyi uygulamaların hayata geçirilip geçirilmediğine bağlı olarak değişir.

Tablo için ortalama istek sayısını bulmak istiyorsanız uygulamanızda bir Otomatik Tamamlama (Yeni) tahminini seçmeden önce kullanıcının ortalama kaç karakter yazdığını analiz edin.

Yer Ayrıntıları (Yeni) ile oturuma dayalı Otomatik Tamamlama (Yeni)

Oturuma dayalı Otomatik Tamamlama (Yeni) özelliğini Yer Ayrıntıları (Yeni) ile kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi Yer Ayrıntıları (Yeni) bilgilerini gerektirdiğinden Otomatik Tamamlama (Yeni) uygulamanızda, istediğiniz yer veri alanlarına bağlı olarak oturum başına bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larına yerleşik olarak) ve geçerli Places SKU'ları kullanılmalıdır.¹

Widget uygulaması
Oturum yönetimi; JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Buna, seçilen tahminle ilgili hem Otomatik Tamamlama (Yeni) istekleri hem de Yer Ayrıntıları (Yeni) isteği dahildir. Yalnızca ihtiyacınız olan Autocomplete (New) veri alanlarını istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programatik uygulama
Otomatik Tamamlama (Yeni) isteklerinizde oturum jetonu kullanın. Seçilen tahminle ilgili Yer Ayrıntıları (Yeni) isteğinde bulunurken aşağıdaki parametreleri ekleyin:

1. Otomatik Tamamlama (Yeni) yanıtındaki yer kimliği
2. Autocomplete (New) isteğinde kullanılan oturum jetonu
3. İhtiyacınız olan Otomatik Tamamlama (Yeni) veri alanlarını belirten fields parametresi

Geocoding API ile istek başına Autocomplete (New)

Autocomplete'i (New) oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmini için Geocoding API'yi çağırın.
Geocoding API, adresleri ve enlem/boylam koordinatlarını sağlar. Dört Autocomplete Requests isteği ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısı yapmanın maliyeti, oturum başına Autocomplete (New) maliyetinden daha düşüktür.¹

Kullanıcılarınızın aradıkları tahmini daha az karakterle almalarına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.

Yalnızca adres uygulamaları için oturuma dayalı Autocomplete (New)

Oturuma dayalı Otomatik Tamamlama (Yeni) özelliğini Yer Ayrıntıları (Yeni) ile kullanın.
Kullanıcı bir Otomatik Tamamlama (Yeni) tahminini seçmeden önce yapmayı beklediğiniz ortalama istek sayısı, oturum başına fiyatlandırma maliyetini aştığından Otomatik Tamamlama (Yeni) uygulamanızda hem Otomatik Tamamlama (Yeni) istekleri hem de ilişkili Yer Ayrıntıları (Yeni) isteği için oturum jetonu kullanılmalıdır. oturum başına. ¹

Widget uygulaması
Oturum yönetimi; JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Buna, seçilen tahminle ilgili hem Otomatik Tamamlama (Yeni) istekleri hem de Yer Ayrıntıları (Yeni) isteği dahildir. Yalnızca ihtiyacınız olan alanları istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programatik uygulama
Autocomplete (New) isteklerinizde oturum jetonu kullanın. Seçilen tahminle ilgili Yer Ayrıntıları (Yeni) isteğinde bulunurken aşağıdaki parametreleri ekleyin:

1. Otomatik Tamamlama (Yeni) yanıtındaki yer kimliği
2. Autocomplete (New) isteğinde kullanılan oturum jetonu
3. Adres ve geometri gibi alanları belirten fields parametresi

Autocomplete (New) isteklerini geciktirmeyi düşünün
Uygulamanızın daha az istek göndermesi için Autocomplete (New) isteğini kullanıcı ilk üç veya dört karakteri yazana kadar geciktirme gibi stratejiler kullanabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Autocomplete (New) istekleri yapılması, kullanıcı yedi karakter yazıp ardından bir Geocoding API isteği yaptığınız bir tahmini seçerse toplam maliyetin 4 Autocomplete (New) istek başına + Geocoding için olacağı anlamına gelir.¹

İstekleri geciktirmek ortalama programatik istek sayınızı dörtten az yapabiliyorsa Geocoding API ile yüksek performanslı Autocomplete (New) uygulamasıyla ilgili kılavuzu takip edebilirsiniz. İsteklerin geciktirilmesinin, her yeni tuş vuruşunda tahminleri görmeyi bekleyen kullanıcı tarafından gecikme olarak algılanabileceğini unutmayın.

Kullanıcılarınızın aradıkları tahmini daha az karakterle bulmalarına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.

---

1. Maliyetler için Google Haritalar Platformu fiyat listelerine bakın.

Performansla ilgili en iyi uygulamalar

Aşağıdaki yönergelerde, Otomatik Tamamlama (Yeni) performansını optimize etme yöntemleri açıklanmaktadır:

• Otomatik Tamamlama (Yeni) uygulamanıza ülkeye özgü kısıtlamalar, konum ağırlığı ve (programatik uygulamalar için) dil tercihleri ekleyin. Widget'lar, dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından aldığı için widget'larda dil tercihine gerek yoktur.
• Autocomplete (New) ile birlikte bir harita varsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
• Kullanıcı, Autocomplete (New) tahminlerinden birini seçmediğinde (genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığı için) daha alakalı sonuçlar elde etmek için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
  • Kullanıcının yalnızca adres bilgisi girmesini bekliyorsanız Geocoding API çağrısında orijinal kullanıcı girişini yeniden kullanın.
  • Kullanıcının belirli bir yer için ad veya adresle sorgu girmesini bekliyorsanız Yer Ayrıntıları (Yeni) isteği kullanın. Sonuçların yalnızca belirli bir bölgede gösterilmesi bekleniyorsa konum ağırlığı kullanın.
  Geocoding API'ye başvurmanın en iyi seçenek olduğu diğer senaryolar şunlardır:
  • Kullanıcılar, bir binadaki belirli birimlerin veya dairelerin adresleri gibi alt tesis adreslerini giriyor. Örneğin, Çekçe "Stroupežnického 3191/17, Praha" adresi, Otomatik Tamamlama (Yeni) özelliğinde kısmi bir tahmin döndürür.
  • Kullanıcılar, New York'ta "23-30 29th St, Queens" veya Hawaii'nin Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleri içeren adresler giriyor.

Konuma göre yönlendirme

location parametresi ve radius parametresi ileterek sonuçları belirli bir alana göre önceliklendirin. Bu, Otomatik Tamamlama'ya (Yeni) tanımlanan alan içindeki sonuçları göstermeyi tercih etmesini söyler. Tanımlanan alanın dışındaki sonuçlar gösterilmeye devam edebilir. Sonuçları yalnızca belirtilen bir ülkedeki yerleri gösterecek şekilde filtrelemek için includedRegionCodes parametresini kullanabilirsiniz.

Uyarı: radius sağlanmazsa location parametresi yoksayılır.

Arama alanı geniş olduğunda, işletme sonuçları genellikle sonuçlarda gösterilecek kadar yüksek sıralamaya sahip olmaz. İşletmelerin karma işletme/coğrafi kod sonuçlarında görünmesini istiyorsanız daha küçük bir yarıçap belirtebilirsiniz. Alternatif olarak, sonuçları yalnızca işletmelerle sınırlamak için types=establishment kullanın.

Konum kısıtlama

locationRestriction parametresini ileterek sonuçları belirli bir alanla kısıtlayın.

Ayrıca, locationRestriction parametresini ekleyerek sonuçları location ve radius parametresiyle tanımlanan bölgeyle kısıtlayabilirsiniz. Bu, Otomatik Tamamlama'ya (Yeni) yalnızca bu bölgedeki sonuçları döndürmesini söyler.

Not: Konum kısıtlamaları yalnızca rotaların tamamına uygulanır. Konum kısıtlamasıyla çakışan bir rotaya göre, konum kısıtlamasının dışında bulunan yapay sonuçlar döndürülebilir.