Aralık ayında San Francisco'da düzenlenecek bir sonraki Google Haritalar Platformu Geliştirici Topluluğu Günü'nde bize katılın. Katılmak için hemen başvurun.

Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Street View Static API'yi kullanmayla ilgili en iyi uygulamalar

HTTP arayüzlerinden oluşan bir koleksiyon olan Google Haritalar Platformu statik web API'leri, doğrudan web sayfanıza yerleştirilecek resimler oluşturur.

Google Haritalar Platformu web hizmetleri, harita uygulamalarınız için coğrafi veriler sağlayan bir HTTP arayüzleri koleksiyonudur.

Bu kılavuzda, resim ve web hizmeti isteklerinizi ayarlamak ve hizmet yanıtlarını işlemek için yararlı olan bazı yaygın uygulamalar açıklanmaktadır. Street View Static API hakkında daha fazla bilgi için geliştirici kılavuzuna bakın.

Street View Static API, statik bir web API'si gibi çalışırken meta veri hizmeti, web hizmeti olarak çalışır. Meta veri hizmeti hakkında daha fazla bilgi için Street View görüntü meta verileri başlıklı makaleyi inceleyin.

Statik web API'si nedir?

Google Haritalar Platformu statik web API'leri, JavaScript veya dinamik sayfa yükleme gerektirmeden web sayfanıza Google Haritalar resmi yerleştirmenize olanak tanır. Statik web API'leri, standart bir HTTPS isteği kullanılarak gönderilen URL parametrelerine göre bir resim oluşturur.

Tipik bir Street View Static API isteği aşağıdaki biçimdedir:

  https://www.googleapis.com/streetview/z/x/y?parameters

Web hizmeti nedir?

Google Haritalar Platformu web hizmetleri, harici hizmetlerden Maps API verileri istemek ve bu verileri Haritalar uygulamalarınızda kullanmak için bir arayüzdür. Bu hizmetler, Google Haritalar Platformu Hizmet Şartları'ndaki Lisans Kısıtlamaları uyarınca bir haritayla birlikte kullanılacak şekilde tasarlanmıştır.

Maps API web hizmetleri, belirli URL'lere HTTP veya HTTPS istekleri göndererek URL parametrelerini ya da JSON biçimli POST verilerini hizmetlere bağımsız değişken olarak iletir. Genellikle bu hizmetler, uygulamanız tarafından ayrıştırılmak veya işlenmek üzere yanıt gövdesinde JSON olarak veri döndürür.

Street View Static API meta veri isteği aşağıdaki biçimdedir:

https://maps.googleapis.com/maps/api/streetview/parameters

SSL ve TLS erişimi

API anahtarlarını kullanan veya kullanıcı verileri içeren tüm Google Haritalar Platformu istekleri için HTTPS gereklidir. Hassas veriler içeren HTTP üzerinden yapılan istekler reddedilebilir.

Geçerli bir URL oluşturma

"Geçerli" bir URL'nin ne olduğu açık gibi görünse de aslında durum tam olarak öyle değildir. Örneğin, bir tarayıcının adres çubuğuna girilen URL özel karakterler (ör."上海+中國") içerebilir. Tarayıcının, iletimden önce bu karakterleri dahili olarak farklı bir kodlamaya çevirmesi gerekir. Aynı şekilde, UTF-8 girişi oluşturan veya kabul eden tüm kodlar, UTF-8 karakterleri içeren URL'leri "geçerli" olarak kabul edebilir ancak bu karakterleri bir web sunucusuna göndermeden önce çevirmesi de gerekir. Bu işleme URL kodlaması veya yüzde kodlaması adı verilir.

Özel karakterler

Tüm URL'lerin Tekdüzen Kaynak Tanımlayıcısı (URI) spesifikasyonunda belirtilen söz dizimine uyması gerektiğinden özel karakterleri çevirmemiz gerekir. Bu, URL'lerin yalnızca ASCII karakterlerinin özel bir alt kümesini içermesi gerektiği anlamına gelir: tanıdık alfanümerik simgeler ve URL'lerde kontrol karakterleri olarak kullanılacak bazı ayrılmış karakterler. Bu tabloda bu karakterler özetlenmektedir:

Geçerli URL karakterlerinin özeti

Ayarlandı	karakterler	URL kullanımı
Alfanümerik	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	Metin dizeleri, şema kullanımı (`http`), bağlantı noktası (`8080`) vb.
Ayrılmamış	- _ . ~	Metin dizeleri
Rezervasyon yapıldı	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	Kontrol karakterleri ve/veya metin dizeleri

Geçerli bir URL oluştururken yalnızca tabloda gösterilen karakterleri içerdiğinden emin olmanız gerekir. Bir URL'yi bu karakter grubunu kullanacak şekilde uyarlamak genellikle iki soruna yol açar: karakterlerin atlanması ve karakterlerin değiştirilmesi:

İşlemek istediğiniz karakterler yukarıdaki kümenin dışında yer alıyorsa. Örneğin, 上海+中國 gibi yabancı dillerdeki karakterlerin yukarıdaki karakterler kullanılarak kodlanması gerekir. Genel kural olarak, boşluklar (URL'lerde izin verilmez) genellikle artı '+' karakteri kullanılarak da temsil edilir.
Karakterler, yukarıdaki grupta ayrılmış karakterler olarak bulunur ancak tam anlamıyla kullanılmaları gerekir. Örneğin, URL'lerde sorgu dizesinin başlangıcını belirtmek için ? kullanılır. "? ve Gizemliler" dizesini kullanmak istiyorsanız '?' karakterini kodlamanız gerekir.

URL kodlaması yapılacak tüm karakterler, '%' karakteri ve UTF-8 karakterlerine karşılık gelen iki karakterli onaltılık değer kullanılarak kodlanır. Örneğin, UTF-8'deki 上海+中國, URL kodlamasıyla %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B olur. ? and the Mysterians dizesi, URL kodlamalı olarak %3F+and+the+Mysterians veya %3F%20and%20the%20Mysterians şeklinde olur.

Kodlanması gereken yaygın karakterler

Kodlanması gereken bazı yaygın karakterler şunlardır:

Güvenli olmayan karakter	Kodlanmış değer
Boşluk	`%20`
"	`%22`
<	`%3C`
>	`%3E`
#	`%23`
%	`%25`
\|	`%7C`

Kullanıcı girişinden aldığınız bir URL'yi dönüştürmek bazen zor olabilir. Örneğin, bir kullanıcı adresi "5th&Main St." olarak girebilir. Genellikle URL'nizi parçalarından oluşturmanız ve tüm kullanıcı girişlerini değişmez karakterler olarak ele almanız gerekir.

Ayrıca URL'ler, tüm Google Haritalar Platformu web hizmetleri ve statik web API'leri için 16.384 karakterle sınırlıdır. Çoğu hizmette bu karakter sınırlamasına nadiren yaklaşılır. Ancak bazı hizmetlerin, uzun URL'lere neden olabilecek çeşitli parametreleri olduğunu unutmayın.

Google API'lerinin ölçülü kullanımı

Kötü tasarlanmış API istemcileri, internet ve sunucular üzerinde ağır yük oluşturabilir. Bu bölümde, API istemcileri için en iyi uygulamalar yer almaktadır. Bu en iyi uygulamaları takip etmek, uygulamanızın API'leri yanlışlıkla kötüye kullanması nedeniyle engellenmesini önlemeye yardımcı olabilir.

Eksponansiyel geri yükleme

Nadir durumlarda isteğinizle ilgili bir sorun yaşanabilir. 4xx veya 5xx HTTP yanıt kodu alabilirsiniz ya da istemciniz ile Google'ın sunucusu arasındaki bir noktada TCP bağlantısı başarısız olabilir. Orijinal istek başarısız olduğunda takip isteği başarılı olabileceğinden, isteği yeniden denemek genellikle faydalı olur. Ancak Google'ın sunucularına tekrar tekrar istek göndermemeniz önemlidir. Bu döngü davranışı, istemciniz ile Google arasındaki ağda aşırı yüklenmeye neden olarak birçok taraf için sorunlara yol açabilir.

Daha iyi bir yaklaşım, denemeler arasındaki gecikmeleri artırarak yeniden denemektir. Gecikme genellikle her denemede çarpımsal bir faktörle artar. Bu yaklaşım, eksponansiyel geri yükleme olarak bilinir.

Örneğin, Time Zone API'ye şu isteği gönderen bir uygulamayı ele alalım:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

Aşağıdaki Python örneğinde, isteğin eksponansiyel geri yükleme ile nasıl yapılacağı gösterilmektedir:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined in the following code isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay on each retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Uygulama çağrı zincirinin üst kısımlarında, kısa aralıklarla tekrarlanan isteklere yol açan yeniden deneme kodu olmadığından emin olun.

Senkronize istekler

Google'ın API'lerine gönderilen çok sayıda senkronize istek, Google'ın altyapısına yönelik dağıtılmış hizmet reddi (DDoS) saldırısı gibi görünebilir ve buna göre değerlendirilebilir. Bu sorunu önlemek için API isteklerinin istemciler arasında senkronize edilmediğinden emin olun.

Örneğin, geçerli saat dilimindeki saati gösteren bir uygulama düşünün. Bu uygulama, gösterilen saatin güncellenebilmesi için istemci işletim sisteminde dakikanın başında uyanmasını sağlayacak bir alarm ayarlıyor olabilir. Uygulamada, bu alarm ile ilişkili işleme kapsamında API çağrısı yapmayın.

Sabit bir alarma yanıt olarak API çağrıları yapmak, API çağrılarının zaman içinde eşit olarak dağıtılması yerine, farklı cihazlar arasında bile dakikanın başına senkronize edilmesine neden olduğu için iyi bir yöntem değildir. Kötü tasarlanmış bir uygulama bunu yaptığında her dakikanın başında normal seviyenin 60 katı trafik artışı yaşanır.

Bunun yerine, uygulamayı rastgele seçilen bir zamana ayarlanmış ikinci bir alarmı olacak şekilde tasarlayabilirsiniz. Bu ikinci alarm tetiklendiğinde uygulama, ihtiyaç duyduğu tüm API'leri çağırır ve sonuçları depolar. Uygulama, dakikanın başında ekranını güncellerken API'yi tekrar çağırmak yerine önceden depolanan sonuçları kullanır. Bu yaklaşımda API çağrıları zaman içinde eşit olarak dağıtılır. Ayrıca API çağrıları, ekran güncellendiğinde oluşturmayı geciktirmez.

Dakikanın başlangıcı dışında, saatin başlangıcı ve her gün gece yarısı gibi diğer yaygın senkronizasyon zamanlarını hedeflemeyin.

Yanıtlar işleniyor

Bir web hizmeti isteğine verilen bireysel yanıtların tam biçimi garanti edilmediğinden (bazı öğeler eksik olabilir veya birden fazla konumda bulunabilir) belirli bir yanıt için döndürülen biçimin farklı sorgular için aynı olduğunu varsaymayın. Bunun yerine, yanıtı işleyin ve ifadeleri kullanarak uygun değerleri seçin.

Bu bölümde, bu değerlerin web hizmeti yanıtlarından dinamik olarak nasıl ayıklanacağı açıklanmaktadır.

Google Haritalar web hizmetleri, anlaşılır ancak kullanıcı dostu olmayan yanıtlar sağlar. Sorgu gerçekleştirirken bir veri kümesi görüntülemek yerine muhtemelen birkaç belirli değeri ayıklamak istersiniz. Genellikle web hizmetinden gelen yanıtları ayrıştırır ve yalnızca sizi ilgilendiren değerleri ayıklar.

Kullanacağınız ayrıştırma şeması, çıkışı JSON biçiminde döndürüp döndürmediğinize bağlıdır. JSON yanıtları, JavaScript nesneleri biçiminde olduğundan istemcide JavaScript içinde işlenebilir.