Place Autocomplete Data API

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

Fatura adresiniz Avrupa Ekonomik Alanı'ndaysa 8 Temmuz 2025'ten itibaren Hizmetler'i 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 otomatik tamamlama istekleri göndermek için Yer Adı Otomatik Tamamlama Veri API'sini 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 gönderin. input özelliği, aranacak dizeyi içerir. Normal bir uygulamada bu değer, kullanıcı 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

Varsayılan olarak, Yer Adı Otomatik Tamamlama tüm yer türlerini sunar, kullanıcının konumuna yakın tahminler için ağırlık 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ı yoksaymasına neden olur. Sonuçları harita sınırlarıyla kısıtlamak yaygın bir uygulamadır. Sonuçları ağırlıklandırma, 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 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 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() yöntemine 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. Birden fazla oturum için aynı jetonun 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 (karakter başına değil) bir 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 sonucu için 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ğırma ve yanıt olarak tahmini yerlerin listesini gösterme
• Kullanıcı sorgusunu nihai Yer Ayrıntıları isteğiyle gruplandırmak için oturum jetonları kullanma.
• Seçilen yerin ayrıntılarını alma ve işaretçi gösterme
• Kullanıcı arayüzü öğelerini gmp-map öğesine yerleştirmek için kontrol yuvalama 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 Autocomplete (New) 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

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

Gelişmiş maliyet optimizasyonu

SKU: Autocomplete Request fiyatlandırmasına erişmek için Autocomplete'in (Yeni) programatik uygulamasını kullanmayı ve Yer Ayrıntıları (Yeni) yerine seçilen yerle ilgili Geocoding API sonuçlarını istemeyi düşünün. 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.

İhtiyaçlarınıza uygun Autocomplete (New) uygulamasını seçme konusunda yardım almak için aşağıdaki soruya verdiğiniz yanıtla ilgili sekmeyi seçin.

Uygulamanız, seçilen tahminin adresi ve enlem/boylamı dışında başka bir bilgi gerektiriyor mu?

Evet, daha fazla ayrıntı gerekiyor

Oturuma dayalı Otomatik Tamamlama (Yeni) özelliğini Yer Ayrıntıları (Yeni) ile kullanın.
Uygulamanız yer adı, işletmenin durumu veya çalışma saatleri gibi Yer Ayrıntıları (Yeni) bilgilerini gerektirdiğinden Otomatik Tamamlama (Yeni) uygulamanızda, istediğiniz yer verisi 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 otomatik olarak JavaScript, Android veya iOS widget'larına yerleştirilmiştir. 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

Hayır, yalnızca adres ve konum bilgisi gerekiyor

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.

Aşağıdaki soruyu yanıtlamak için bir kullanıcının uygulamanızda Otomatik Tamamlama (Yeni) tahminini seçmeden önce ortalama kaç karakter yazdığını analiz edin.

Kullanıcılarınız ortalama dört veya daha az istekte bir Autocomplete (New) tahminini seçiyor mu?

Evet

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.

Hayır

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

Widget uygulaması
Oturum yönetimi; JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Buna hem Otomatik Tamamlama (Yeni) istekleri hem de seçilen tahminle ilgili 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
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. 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 Otomatik Tamamlama (Yeni) istekleri gönderdiğinizde, kullanıcı yedi karakter yazıp bir Geocoding API isteği gönderdiğiniz bir tahmini seçerse toplam maliyet 4 Otomatik Tamamlama (Yeni) İstek Başına + Geocoding maliyeti olur.¹

İ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 etmenin yolları 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) özelliğine bir harita eşlik ediyorsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
• Kullanıcı, Otomatik Tamamlama (Yeni) tahminlerinden birini seçmediğinde (genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığı için) daha alakalı sonuçlar elde etmek amacıyla orijinal kullanıcı girişini yeniden kullanabilirsiniz:
  • Kullanıcının yalnızca adres bilgilerini 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ıklandırmayı 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.

Konum tercihi

Bir location parametresi ve bir radius parametresi ileterek sonuçları belirli bir alana yönlendirin. 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.