Coğrafi Kodlama Hizmeti

Genel Bakış

Coğrafi kodlama, adresleri (ör. "1600 Amphitheatre Parkway, Mountain View, CA") coğrafi koordinatlara (ör. enlem 37,423021 ve boylam -122,083739) dönüştürme işlemidir. Bu koordinatları, işaretçi yerleştirmek veya haritayı konumlandırmak için kullanabilirsiniz.

Ters coğrafi kodlama, coğrafi koordinatları kullanıcı tarafından okunabilir bir adrese dönüştürme işlemidir (Ters coğrafi kodlama (Adres Arama) bölümüne bakın).

Belirli bir yer kimliğinin adresini bulmak için coğrafi kodlayıcıyı da kullanabilirsiniz.

Maps JavaScript API, kullanıcı girişinden dinamik olarak coğrafi kodlama ve tersine coğrafi kodlama yapmak için bir coğrafi kodlayıcı sınıfı sağlar. Bunun yerine statik ve bilinen adreslerin coğrafi kodlamasını yapmak istiyorsanız Coğrafi kodlama web hizmeti sayfasını inceleyin.

Başlayın

Maps JavaScript API'de Coğrafi Kodlama hizmetini kullanmadan önce, Google Cloud Konsolu'nda Maps JavaScript API için oluşturduğunuz projede Geocoding API'nin etkinleştirildiğinden emin olun.

Etkin API'lerinizin listesini görüntülemek için:

  1. Google Cloud Console'a gidin.
  2. Proje seç düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve Aç'ı tıklayın.
  3. Kontrol panelindeki API listesinde Geocoding API'yi bulun.
  4. API'yi listede görürseniz hazırsınız demektir. API listede yoksa etkinleştirin:
    1. Sayfanın üst kısmında API'yi etkinleştir'i seçerek Kitaplık sekmesini görüntüleyin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı da seçebilirsiniz.
    2. Geocoding API'yi arayın ve ardından sonuçlar listesinden seçin.
    3. ETKİNLEŞTİR'i seçin. İşlem tamamlandığında Kontrol paneli'ndeki API listesinde Coğrafi Kodlama API'si görünür.

Fiyatlandırma ve politikalar

Fiyatlandırma

JavaScript Coğrafi Kodlama hizmetinin fiyatlandırması ve kullanım politikaları hakkında bilgi edinmek için Geocoding API'nin Kullanım ve Faturalandırma bölümüne bakın.

Politikalar

Coğrafi Kodlama hizmeti kullanımınız Geocoding API için Politikalar'a uygun olmalıdır.

Coğrafi Kodlama İstekleri

Google Haritalar API'sinin harici bir sunucuya çağrı yapması gerektiğinden, Coğrafi Kodlama hizmetine erişim ayarsızdır. Bu nedenle, istek tamamlandıktan sonra çalıştırılacak bir geri çağırma yöntemi iletmeniz gerekir. Bu geri çağırma yöntemi sonuçları işler. Coğrafi kodlayıcının birden fazla sonuç döndürebileceğini unutmayın.

google.maps.Geocoder oluşturucu nesnesini kullanarak kodunuz içinde Google Haritalar API'si coğrafi kodlama hizmetine erişirsiniz. Geocoder.geocode() yöntemi, coğrafi kodlama hizmetine bir istek göndererek giriş terimlerini ve yanıt alındıktan sonra çalıştırılacak bir geri çağırma yöntemini içeren bir GeocoderRequest nesne değişmez ifadesi iletir.

GeocoderRequest nesne değişmezi aşağıdaki alanları içerir:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Zorunlu parametreler: Aşağıdaki alanlardan yalnızca birini sağlamanız gerekir:

  • address: Coğrafi kodlamak istediğiniz adres.
         veya
    location — Kullanıcıların okuyabileceği en yakın adresi elde etmek istediğiniz LatLng (veya LatLngLiteral). Coğrafi kodlayıcı, tersine coğrafi kodlama gerçekleştirir. Daha fazla bilgi için Geri Coğrafi Kodlama bölümüne bakın.
         veya
    placeId - Kullanıcıların okuyabileceği en yakın adresi edinmek istediğiniz yerin yer kimliği. Yer kimliği için adres alma hakkında daha fazla bilgi edinin.

İsteğe bağlı parametreler:

  • bounds: Coğrafi kodlama sonuçlarını daha belirgin bir şekilde yönlendirmek için kullanılanLatLngBounds bounds parametresi, coğrafi kodlayıcıdan gelen sonuçları yalnızca etkiler, tamamen kısıtlamaz. Görüntü alanı önyargısı hakkında daha fazla bilgi için aşağıya bakın.
  • componentRestrictions: Sonuçları belirli bir alanla sınırlamak için kullanılır. Bileşen filtreleme hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.
  • region: İki karakterli (sayısal olmayan) Unicode bölge alt etiketi olarak belirtilen bölge kodu. Çoğu durumda bu etiketler doğrudan bilinen ccTLD ("üst düzey alan") iki karakterli değerlerle eşlenir. region parametresi, coğrafi kodlayıcıdan gelen sonuçları yalnızca etkiler, tamamen kısıtlamaz. Bölge kodu önyargısı hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.
  • extraComputations: Bu parametre için izin verilen tek değer ADDRESS_DESCRIPTORS'dur. Daha fazla bilgi için adres tanımlayıcıları bölümüne bakın.
  • fulfillOnZeroResults: Yanıtta ZERO_RESULT durumundaki vaadi yerine getirin. Bu, sıfır coğrafi kodlama sonucu olsa bile ek yanıt düzeyi alanları döndürülebileceği için istenebilir. Daha fazla bilgi için Sonuç Olmadığında Siparişin Gerçekleşmesi başlıklı makaleyi inceleyin.

Coğrafi Kodlama Yanıtları

Coğrafi kodlama hizmeti, coğrafi kodlayıcının sonuçları alındıktan sonra çalıştırılacak bir geri çağırma yöntemi gerektirir. Bu geri çağırma, results ve status kodunu bu sırayla tutmak için iki parametre iletmelidir.

Coğrafi Kodlama Sonuçları

GeocoderResult nesnesi tek bir coğrafi kodlama sonucunu temsil eder. Coğrafi kodlama isteği birden fazla sonuç nesnesi döndürebilir:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

Bu alanlar aşağıda açıklanmıştır:

  • types[], döndürülen sonucun adres türünü belirten bir dizidir. Bu dizi, sonuçta döndürülen özellik türünü tanımlayan sıfır veya daha fazla etiket içerir. Örneğin, "Chicago" için bir coğrafi kod, "Chicago"nun şehir olduğunu belirten "locality" değerini ve siyasi bir varlık olduğunu belirten "political" değerini döndürür. Adres türleri ve adres bileşeni türleri hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.
  • formatted_address, bu konumun okunabilir adresini içeren bir dizedir.

    Bu adres genellikle posta adresine eşdeğerdir. Birleşik Krallık gibi bazı ülkelerde, lisanslama kısıtlamaları nedeniyle gerçek posta adreslerinin dağıtımına izin verilmediğini unutmayın.

    Biçimlendirilmiş adres, mantıksal olarak bir veya daha fazla adres bileşeninden oluşur. Örneğin, "111 8th Avenue, New York, NY" adresi şu bileşenlerden oluşur: "111" (sokak numarası), "8th Avenue" (rota), "New York" (şehir) ve "NY" (ABD eyaleti).

    Biçimlendirilmiş adresi programlı bir şekilde ayrıştırmayın. Bunun yerine, biçimlendirilmiş adres alanına ek olarak API yanıtının içerdiği bağımsız adres bileşenlerini kullanmanız gerekir.

  • address_components[], bu adres için geçerli olan ayrı bileşenleri içeren bir dizidir.

    Her adres bileşeni genellikle aşağıdaki alanları içerir:

    • types[], adres bileşeninin türünü gösteren bir dizidir. Desteklenen türler listesine bakın.
    • long_name, Coğrafi Kodlayıcı tarafından döndürülen adres bileşeninin tam metin açıklaması veya adıdır.
    • short_name, varsa adres bileşeninin kısaltılmış metin adıdır. Örneğin, Alaska eyaleti için bir adres bileşeninde 2 harfli posta kısaltması kullanılarak long_name "Alaska" ve short_name "AK" bulunabilir.

    address_components[] dizisiyle ilgili aşağıdaki gerçeklere dikkat edin:

    • Adres bileşenleri dizisi, formatted_address öğesinden daha fazla bileşen içerebilir.
    • Dizi, formatted_address içinde yer alanların dışında, bir adres içeren tüm siyasi varlıkları içermeyebilir. Belirli bir adres içeren tüm siyasi varlıkları almak için tersine coğrafi kodlama kullanmanız ve adresin enlem/boylam değerlerini isteğe parametre olarak iletmeniz gerekir.
    • Yanıt biçiminin istekler arasında aynı kalacağı garanti edilmez. Özellikle address_components sayısı, istenen adrese göre değişir ve aynı adres için zaman içinde değişebilir. Bir bileşen, dizideki konumunu değiştirebilir. Bileşenin türü değişebilir. Daha sonraki bir yanıtta belirli bir bileşen eksik olabilir.

    Adres türleri ve adres bileşeni türleri hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

  • partial_match, coğrafi kodlayıcının orijinal istek için tam eşleşme döndürmediğini, ancak istenen adresin bir kısmını eşleştirebildiğini gösterir. Yazım hataları ve/veya eksik adres olup olmadığını kontrol etmek için orijinal isteği inceleyebilirsiniz.

    Kısmi eşleşmeler en sık, istekte belirttiğiniz bölgede bulunmayan açık adresler için gerçekleşir. Bir istek aynı konumdaki iki veya daha fazla konumla eşleştiğinde kısmi eşleşmeler de döndürülebilir. Örneğin, "Hillpar St, Bristol, UK" hem Henry Street hem de Henrietta Street için kısmi bir eşleşme döndürür. İstek yanlış yazılmış bir adres bileşeni içeriyorsa coğrafi kodlama hizmetinin alternatif bir adres önerebileceğini unutmayın. Bu şekilde tetiklenen öneriler de kısmi eşleşme olarak işaretlenir.

  • place_id, bir yerin benzersiz tanımlayıcısıdır ve diğer Google API'leriyle kullanılabilir. Örneğin, yerel bir işletmenin telefon numarası, çalışma saatleri, kullanıcı yorumları gibi ayrıntılarını almak için place_id ile Google Places API kitaplığını kullanabilirsiniz. Yer kimliğine genel bakış başlıklı makaleyi inceleyin.
  • postcode_localities[], bir posta kodunda bulunan tüm yerleşim yerlerini belirten bir dizidir ve yalnızca sonuç birden fazla yerleşim yeri içeren bir posta kodu olduğunda mevcuttur.

  • geometry aşağıdaki bilgileri içerir:

    • location,coğrafi kodlanmış enlem ve boylam değerini içerir. Bu konumu biçimlendirilmiş dize olarak değil, LatLng nesnesi olarak döndürdüğümüzü unutmayın.
    • location_type, belirtilen konumla ilgili ek verileri depolar. Aşağıdaki değerler desteklenir:
      • ROOFTOP, döndürülen sonucun tam bir coğrafi kod yansıttığını gösterir.
      • RANGE_INTERPOLATED döndürülen sonucun, iki kesin nokta (ör. kavşaklar) arasında interpolasyon uygulanmış bir yaklaşık değeri (genellikle bir yolda) yansıttığını gösterir. Bir sokak adresi için çatıdan alınan coğrafi kodlar kullanılamadığında genellikle interpolate edilmiş sonuçlar döndürülür.
      • GEOMETRIC_CENTER döndürülen sonucun, poli çizgi (ör. sokak) veya poligon (bölge) gibi bir sonucun geometrik merkezi olduğunu gösterir.
      • APPROXIMATE döndürülen sonucun yaklaşık olduğunu gösterir.

    • viewport, döndürülen sonuç için önerilen görüntü alanını depolar.
    • bounds (isteğe bağlı olarak döndürülür), döndürülen sonucu tamamen içerebilen LatLngBounds değerini saklar. Bu sınırların önerilen görüntü alanı ile eşleşmeyebileceğini unutmayın. (Örneğin San Francisco, teknik olarak şehrin bir parçası olan ancak görüntü alanına döndürülmemesi gereken Farallon Adaları'nı da kapsar.)

Adresler, tarayıcının tercih edilen dil ayarı veya language parametresi kullanılarak API JavaScript'i yüklenirken belirtilen dil kullanılarak Geocoder tarafından döndürülür. (Daha fazla bilgi için yerelleştirme bölümüne bakın.)

Adres Türleri ve Adres Bileşeni Türleri

GeocoderResult bölümündeki types[] dizisi, adres türünü belirtir. types[] dizisi, belirli bir adres bileşeninin türünü belirtmek için GeocoderAddressComponent içinde de döndürülebilir. Coğrafi kodlayıcı tarafından döndürülen adreslerin birden fazla türü olabilir. Bu türler etiket olarak kabul edilebilir. Örneğin, birçok şehir political ve locality türüyle etiketlenir.

Coğrafi kodlayıcı, hem adres türlerinde hem de adres bileşeni türlerinde aşağıdaki türleri destekler ve döndürür:

  • street_address, tam açık adresi gösterir.
  • route, adlandırılmış bir rotayı (ör. "TR 101") gösterir.
  • intersection, genellikle iki ana yolu kapsayan ana bir kesişimi gösterir.
  • political, siyasi bir tüzel kişiyi belirtir. Bu tür genellikle bir sivil yönetim poligonunu gösterir.
  • country, ulusal siyasi kuruluşu gösterir ve genellikle Coğrafi Kodlayıcı tarafından döndürülen en yüksek sipariş türüdür.
  • administrative_area_level_1, ülke düzeyinin altında birinci dereceden bir sivil tüzel kişiyi belirtir. ABD'de bu idari düzeyler eyalettir. Tüm uluslar bu idari düzeylerde değildir. Çoğu durumda, management_area_level_1 kısa adları, ISO 3166-2 alt bölümleri ve yaygın olarak dağıtılan diğer listelerle yakından eşleşir. Ancak coğrafi kodlama sonuçlarımız çeşitli sinyallere ve konum verilerine dayandığından bu durum garanti edilmez.
  • administrative_area_level_2, ülke düzeyinin altında ikinci düzey bir sivil tüzel kişiyi gösterir. Bu idari düzeyler Amerika Birleşik Devletleri'nde ilçelerdir. Tüm uluslar bu idari düzeylerde değildir.
  • administrative_area_level_3, ülke düzeyinin altında üçüncü taraf bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.
  • administrative_area_level_4, ülke düzeyinin altında dördüncü dereceden bir sivil tüzel kişiyi gösterir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.
  • administrative_area_level_5, ülke düzeyinin altında beşinci düzey bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.
  • administrative_area_level_6, ülke düzeyinin altında altıncı dereceden bir sivil tüzel kişiyi gösterir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.
  • administrative_area_level_7, ülke düzeyinin altında yedinci düzey sivil tüzel kişiyi gösterir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.
  • colloquial_area, varlık için yaygın olarak kullanılan bir alternatif adı gösterir.
  • locality, anonim bir şehir veya kasaba siyasi tüzel kişiliğini belirtir.
  • sublocality, bir semtin altında birinci dereceden bir sivil tüzel kişiyi belirtir. Bazı konumlar için ek türlerden biri alınabilir: sublocality_level_1 - sublocality_level_5. Her alt konum düzeyi bir sivil tüzel kişidir. Büyük sayılar daha küçük bir coğrafi alanı belirtir.
  • neighborhood, adlandırılmış bir mahalleyi gösterir.
  • premise, genellikle ortak bir ada sahip olan bir bina veya bina topluluğu olan adlandırılmış bir konumu gösterir.
  • subpremise, tesis düzeyinin altında adreslenebilir bir varlığı (ör. apartman, daire veya daire) belirtir.
  • plus_code, enlem ve boylamdan türetilen kodlanmış bir konum referansını gösterir. Artı kodları, var olmadıkları yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı durumlarda) açık adreslerin yerine kullanılabilir. Ayrıntılar için https://plus.codes sayfasına bakın.
  • postal_code, ülke içindeki posta postaları için kullanılan posta kodunu belirtir.
  • natural_feature belirgin bir doğal özelliği gösterir.
  • airport, bir havaalanını gösterir.
  • park, adlandırılmış bir parkı gösterir.
  • point_of_interest, adlandırılmış bir önemli yeri gösterir. Bu "ÖY"ler, genellikle "Empire State Binası" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca uymayan önemli yerel varlıklardır.

Boş bir tür listesi, belirli adres bileşeni için bilinen bir tür olmadığını gösterir (örneğin, Fransa'daki Lieu-dit).

Adres bileşenleri, yukarıdakilere ek olarak aşağıdaki türleri de içerebilir.

Not: Bu liste tam kapsamlı değildir ve değişebilir.

  • floor bir bina adresinin katını gösterir.
  • establishment genellikle henüz sınıflandırılmamış bir yeri gösterir.
  • landmark, navigasyona yardımcı olmak için referans olarak kullanılan yakındaki bir yeri gösterir.
  • point_of_interest, adlandırılmış bir önemli yeri gösterir.
  • parking, bir otopark veya otopark olduğunu belirtir.
  • post_box, belirli bir posta kutusunu belirtir.
  • postal_town, bazı ülkelerde posta adresleri için kullanılan locality ve sublocality gibi coğrafi alanlardan oluşan bir gruplandırmayı belirtir.
  • room, bina adresinin bulunduğu odayı gösterir.
  • street_number tam sokak numarasını gösterir.
  • bus_station, train_station ve transit_station otobüs, tren veya toplu taşıma durağının konumunu belirtir.

Durum Kodları

status kodu aşağıdaki değerlerden birini döndürebilir:

  • "OK", hiçbir hata oluşmadığını belirtir; adresin başarıyla ayrıştırıldığını ve en az bir coğrafi kod döndürüldüğünü gösterir.
  • "ZERO_RESULTS", coğrafi kodlamanın başarılı olduğunu ancak hiçbir sonuç döndürmediğini gösterir. Bu durum, coğrafi kodlayıcıya var olmayan bir address kodundan geçilmesi durumunda ortaya çıkabilir.
  • "OVER_QUERY_LIMIT", kotanızı aştığınızı gösteriyor.
  • "REQUEST_DENIED", isteğinizin reddedildiğini gösterir. Web sayfasının coğrafi kodlayıcıyı kullanmasına izin verilmiyor.
  • "INVALID_REQUEST" genellikle sorgunun (address, components veya latlng) eksik olduğunu gösterir.
  • "UNKNOWN_ERROR", isteğin bir sunucu hatası nedeniyle işlenemediğini gösterir. Tekrar denerseniz istek başarılı olabilir.
  • "ERROR", isteğin zaman aşımına uğradığını veya Google sunucularıyla iletişime geçme Tekrar denerseniz istek başarılı olabilir.

Bu örnekte, bir adresi coğrafi kodlayıp döndürülen enlem ve boylam değerlerine bir işaretçi yerleştiriyoruz. İşleyicinin anonim işlev değişmez ifadesi olarak iletildiğini unutmayın.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Örneği görüntüleyin.

Görüntü alanı önyargısı

Coğrafi Kodlama Hizmeti'ne, belirli bir görüntü alanındaki (kenarlık kutusu olarak ifade edilir) sonuçları tercih etmesini talimat verebilirsiniz. Bunu, bu görüntü alanının sınırlarını tanımlamak için GeocoderRequest nesne değişmezindeki bounds parametresini ayarlayarak yaparsınız. Eğilimlendirmenin yalnızca sınırlar dahilindeki sonuçları tercih ettiğini unutmayın. Bu sınırların dışında daha alakalı sonuçlar varsa bunlar dahil edilebilir.

Örneğin, "Winnetka" için bir coğrafi kod genellikle Chicago'nun şu banliyösünü döndürür:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

Ancak Los Angeles'taki San Fernando Vadisi için bir sınır kutusu tanımlayan bir bounds parametresi belirtmek, bu coğrafi kodlamanın söz konusu konumda "Winnetka" adlı mahalleyi döndürmesine neden olur:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Bölge Kodu Eğilimi

Coğrafi Kodlama Hizmeti'ni, region parametresini kullanarak belirli bir bölgeye yönelik sonuçlar döndürecek şekilde ayarlayabilirsiniz. Bu parametre, iki karakterli (sayısal olmayan) Unicode bölge alt etiketi olarak belirtilen bir bölge kodu alır. Bu etiketler doğrudan bilinen ccTLD ("üst düzey alan") iki karakterli değerlerle (ör. "co.uk"taki "uk") eşlenir. Bazı durumlarda region etiketi, bazen ccTLD değerlerinden farklı olan ISO-3166-1 kodlarını da destekler (ör. "Büyük Britanya" için "GB").

region parametresi kullanıldığında:

  • Yalnızca bir ülke veya bölge belirtin. Birden fazla değer yok sayılır ve isteğin başarısız olmasına neden olabilir.
  • Yalnızca iki karakterli bölge alt etiketleri (Unicode CLDR biçimi) kullanın. Diğer tüm girişler hataya neden olur.
  • Yalnızca Google Haritalar Platformu Kapsam Ayrıntıları bölümünde listelenen ülke ve bölgeler desteklenir.

Coğrafi kodlama istekleri, ana Google Haritalar uygulamasının coğrafi kodlama sunduğu her alan için gönderilebilir. Eğilimlendirmenin yalnızca belirli bir alanla ilgili sonuçları tercih ettiğini unutmayın. Bu alanın dışında daha alakalı sonuçlar varsa bunlar da dahil edilebilir.

Örneğin, Coğrafi Kodlama Hizmeti'nin varsayılan alanı ABD olarak ayarlandığından "Toledo" için bir coğrafi kod şu sonucu döndürür:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

region alanı 'es' (İspanya) olarak ayarlanmış "Toledo" için bir coğrafi kod, İspanya'daki şehri döndürür:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Bileşen Filtrelemesi

Coğrafi Kodlama Hizmeti'ni, bileşen filtresi kullanarak belirli bir alana Filtreyi componentRestrictions parametresinde belirtin. Filtre değerleri, diğer coğrafi kodlama istekleriyle aynı yazım düzeltme ve kısmi eşleme yöntemlerini destekler.

Coğrafi kodlayıcı yalnızca bileşen filtrelerinin tümüyle eşleşen sonuçları döndürür. Yani filtre özelliklerini VE değil VEYA olarak değerlendirir.

Bileşen filtresi aşağıdaki öğelerden en az birini içerir:

  • route, bir rotanın uzun veya kısa adıyla eşleşir.
  • locality, yerellik ve alt yerellik türleriyle eşleşir.
  • administrativeArea, idari bölgenin tüm seviyeleriyle eşleşir.
  • postalCode, posta kodlarını ve posta kodu ön eklerini eşleştirir.
  • country bir ülke adıyla veya iki harfli ISO 3166-1 ülke koduyla eşleşir. Not: API, ülkeleri tanımlamak için ISO standardını kullanır ve filtreleme, ülkenin ilgili ISO kodu kullanıldığında en iyi şekilde çalışır.

Aşağıdaki örnekte, country ve postalCode'e göre filtreleme yapmak için componentRestrictions parametresinin kullanımı gösterilmektedir:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Sıfır sonuçla sipariş karşılama

Tersine coğrafi kodlama için varsayılan olarak status=ZERO_RESULTS adresinde söz bozulur. Ancak bu durumda plus_code ve address_descriptor'ün ek yanıt düzeyi alanları doldurulmaya devam edebilir. fulfillOnZeroResults parametresi için "true" değeri sağlanırsa bu değer doldurulur. fulfillOnZeroResults parametresi için doğru değeri sağlanırsa söz bozulmaz ve varsa bu ek alanlara sözden erişilebilir.

Aşağıda, Antarktika'daki bir enlem/boylam için bu davranışa dair bir örnek verilmiştir. Ters coğrafi kodlama sonucu olmasa bile fulfillOnZeroResults=true değerini ayarlarsak söz konusu yerdeki artı kodunu yazdırabiliriz. 

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Adres Tanımlayıcıları

Adres tanımlayıcıları, önemli yerleri ve alanları kullanarak bir konumu tanımlamaya yardımcı olan ek bilgiler içerir. Özelliği keşfetmek için adres tanımlayıcıları demosuna göz atın.

Adres tanımlayıcıları, extraComputations parametresi kullanılarak etkinleştirilebilir. Yanıtınızda adres tanımlayıcıları almak için extra_computations=ADDRESS_DESCRIPTORS değerini bir coğrafi kodlama isteğine, tersine coğrafi kodlama isteğine veya yer coğrafi kodlama isteğine ekleyin.

Yer coğrafi kodlaması örneği

Aşağıdaki sorgu, Delhi'deki bir yerin adresini içerir.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

Tersine coğrafi kodlama örneği

Aşağıdaki sorgu, Delhi'deki bir konumun enlem/boylam değerini içerir.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Adres Açıklayıcısı Örneği

address_descriptor örneği aşağıda verilmiştir.

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

Her address_descriptor nesnesinde iki dizi vardır: landmarks ve areas. landmarks dizisi, istenen koordinata yakınlık, yer işaretinin yaygınlığı ve görünürlüğü dikkate alınarak alaka düzeyine göre sıralanmış en fazla 5 sonuç içerir. Her bir dönüm noktası sonucu aşağıdaki değerleri içerir:

  • place_id, önemli yerler sonucunun yer kimliğidir. Yer kimliğine genel bakış başlıklı makaleyi inceleyin.
  • display_name, yer işaretinin görünen adıdır ve language_code ile text içerir.
  • straight_line_distance_meters, giriş koordinatı ile önemli noktalar sonucu arasındaki noktadan noktaya mesafedir (metre cinsinden).
  • travel_distance_meters, yol ağı kullanılarak (yol kısıtlamaları dikkate alınmadan) giriş koordinatı ile önemli nokta sonucu arasındaki katedilen mesafedir.
  • spatial_relationship, giriş koordinatı ile yer işaretleri sonucu arasındaki tahmini ilişkidir:
    • Aşağıdakilerden hiçbiri geçerli olmadığında varsayılan ilişki "NEAR" olur.
    • Giriş koordinatı, belirgin işaretle ilişkili yapının sınırları içindeyse "WITHIN".
    • Giriş koordinatı doğrudan yer işaretinin veya yer işaretinin erişim noktasının hemen yanında olduğunda "BESIDE".
    • Giriş koordinatı, rotanın diğer tarafındaki yer işaretinin tam karşısında olduğunda "ACROSS_THE_ROAD".
    • Giriş koordinatı yer işaretiyle aynı rota üzerindeyse ancak "BESIDES" veya "ACROSS_THE_ROAD" değilse "DOWN_THE_ROAD".
    • Giriş koordinatı, yer işareti olarak dik bir rota üzerindeyse (tek bir dönüşle sınırlıdır) "AROUND_THE_CORNER".
    • "BEHIND" Giriş koordinatı, yer işaretine yakın ancak erişim noktasından uzak olduğunda.
  • types, yer işaretinin yer türleridir.

areas nesnesi en fazla 3 yanıt içerir ve semtler, alt yerel bölgeler ve büyük siteler gibi küçük bölgeleri temsil eden yerlerle sınırlıdır. İstenen koordinatı içeren alanlar önce listelenir ve en küçükten en büyüğe doğru sıralanır. Her areas sonucu aşağıdaki değerleri içerir:

  • place_id, alanlar sonucunun yer kimliğidir. Yer kimliğine genel bakış başlıklı makaleyi inceleyin.
  • display_name, alanın görünen adıdır ve language_code ile text içerir.
  • containment, giriş koordinatı ile alanlar sonucu arasındaki tahmini kapsayıcı ilişkidir:
    • Aşağıdakilerden hiçbiri geçerli olmadığında varsayılan ilişki "NEAR" olur.
    • Giriş koordinatı alanın merkezine yakın olduğunda "WITHIN".
    • Giriş koordinatı alanın kenarına yakın olduğunda "OUTSKIRTS".

Adres Açıklayıcı Kapsamı

Adres tanımlayıcıları, Hindistan için GA'dadır. Hindistan'da adres tanımlayıcılarının kullanımı ek ücrete tabi değildir ve kullanım, mevcut Coğrafi Kodlama (Hindistan) Essentials SKU'su kapsamındadır.

Geri bildirim

Bu özellik tüm bölgelerde kullanılabilir. Bu özellik Hindistan için GKST'de, diğer tüm bölgeler için ise GKST öncesi deneysel lansman aşamasındadır. Geri bildirimlerinizi bekliyoruz:

Tersine Coğrafi Kodlama (Adres Arama)

Coğrafi kodlama terimi genellikle, insanlar tarafından okunabilen bir adresi haritadaki bir konuma dönüştürmeyi ifade eder. Bunun tam tersini yapmak, yani haritadaki bir konumu okunabilir bir adrese dönüştürmek ters coğrafi kodlama olarak bilinir.

Metin biçiminde bir address yerine, location parametresinde virgülle ayrılmış bir enlem/boylam çifti sağlayın.

Aşağıdaki örnekte, bir enlem/boylam değeri coğrafi kodlanır ve harita bu konumda ortalanır. Ardından, biçimlendirilmiş adresi içeren bir bilgi penceresi açılır:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
Örneği görüntüleyin

Örneği Deneyin

Önceki örnekte results[0] seçerek ilk sonucu gösterdiğimizi unutmayın. Ters coğrafi kodlayıcı genellikle birden fazla sonuç döndürür. Coğrafi kodlu adresler yalnızca posta adresleri değil, bir konumu coğrafi olarak adlandırmanın her yoludur. Örneğin, Chicago şehrindeki bir noktanın coğrafi kodlaması yapılırken coğrafi kodlanmış nokta sokak adresi, şehir (Chicago), eyalet (Illinois) veya ülke (ABD) olarak etiketlenebilir. Hepsi coğrafi kodlayıcının adresleridir. Ters coğrafi kodlayıcı bu sonuçların tümünü döndürür.

Ters coğrafi kodlayıcı, siyasi varlıkları (ülkeler, iller, şehirler ve semtler), açık adresleri ve posta kodlarını eşleştirir.

Yukarıdaki sorgunun döndürebileceği adres listesinin bir örneği aşağıda verilmiştir: 

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

Adresler, en iyi eşleşmeden en az eşleşmeye göre döndürülür. Genellikle, bu örnekte olduğu gibi, en belirgin sonuç daha doğru adrestir. En belirgin açık adresten mahalle, şehir, ilçe, eyalet gibi daha az belirgin siyasi oluşumlara kadar farklı adres türlerini döndürdüğümüzü unutmayın. Daha genel bir adresle eşleştirmek istiyorsanız results[].types alanını inceleyebilirsiniz.

Not: Tersine coğrafi kodlama kesin bir bilim değildir. Coğrafi kodlayıcı, belirli bir tolerans dahilinde en yakın adreslenebilir konumu bulmaya çalışır.

Yer kimliği için adres alma

Belirli bir yer kimliğinin adresini bulmak için placeId sağlayın. Yer kimliği, diğer Google API'leriyle kullanılabilen benzersiz bir tanımlayıcıdır. Örneğin, Roads API tarafından döndürülen placeId değerini sağlayarak bir noktanın adresini alabilirsiniz. Yer kimlikleri hakkında daha fazla bilgi için yer kimliklerine genel bakış başlıklı makaleyi inceleyin.

placeId sağladığınızda istek aşağıdaki alanlardan hiçbirini içeremez:

  • address
  • latLng
  • location
  • componentRestrictions

Aşağıdaki örnekte bir yer kimliği kabul edilir, ilgili adres bulunur ve harita bu konumda ortalanır. Ayrıca, ilgili yerin biçimlendirilmiş adresini gösteren bir bilgi penceresi de açılır:

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
Örneği görüntüleyin

Örneği Deneyin