Varış noktası arama

Avrupa Ekonomik Alanı (AEA) geliştiricileri

A Destination kullanıcının ulaşmak veya gezinmek istediği önemli bir ilgi alanını ya da belirli bir konumu ifade eder. Destination, gezinme noktaları, önemli yerler, girişler ve bina planları gibi bilgileri içerebilir.

Geocoding API'nin SearchDestinations uç noktası, adres, yer kimliği veya enlem ve boylam koordinatları gibi farklı giriş ölçütlerine göre çeşitli hedefler hakkında ayrıntılı bilgi almanızı sağlar.

Varış noktası arama isteği

Hedef arama isteği, şu biçimde bir URL'ye yapılan HTTP POST isteğidir:

https://geocode.googleapis.com/v4alpha/geocode/destinations

JSON istek gövdesindeki veya üstbilgilerdeki tüm parametreleri POST isteğinin bir parçası olarak iletin. Örneğin:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

Hedef aramak için konumu 3 şekilde belirtebilirsiniz:

  • Adres
  • Yer kimliği
  • Enlem ve boylam koordinatları

Adrese göre hedef arama

Adresi yapılandırılmamış bir dize olarak belirtebilirsiniz:

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

veya postalAddress olarak:

curl -X POST -d '{
  "addressQuery": {
    "address": {
      "addressLines": ["601 S Bernardo Ave"],
      "locality": "Sunnyvale",
      "postalCode": "94087",
      "administrativeArea": "CA",
      "regionCode": "US"
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

Genellikle bir HTML formunda yakalanan adres bileşenlerini işlerken postalAddress biçimini kullanırsınız.

Yer kimliğine göre hedef arama

Yer kimliği sağlayarak bir hedefi alabilirsiniz:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

Konuma göre hedef arama

Enlem ve boylam koordinatlarını girerek bir hedef arayabilirsiniz:

curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

İstek göndermek için OAuth kullanma

Geocoding API v4, kimlik doğrulama için OAuth 2.0'ı destekler. Coğrafi Kodlama API'si ile OAuth'u kullanmak için OAuth jetonuna doğru kapsam atanmalıdır. Geocoding API, Destinations uç noktasıyla kullanılmak üzere aşağıdaki kapsamları destekler:

  • https://www.googleapis.com/auth/maps-platform.geocode — Tüm Geocoding API uç noktalarıyla kullanılır.

Ayrıca, tüm Geocoding API uç noktaları için genel https://www.googleapis.com/auth/cloud-platform kapsamını kullanabilirsiniz. Bu kapsam, tüm uç noktalara erişime izin veren genel bir kapsam olduğundan geliştirme sırasında kullanışlıdır ancak üretimde kullanışlı değildir.

Daha fazla bilgi ve örnek için OAuth'u kullanma başlıklı makaleyi inceleyin.

Hedef arama yanıtı

Konumla ilgili yakın çevre bağlamı

Arama Hedefleri yanıtı, konum hakkında zengin ve hiper yerel bağlam bilgisi sağlar. Temel alanlar şunlardır:

  • primary: İsteğin sorgusunda tanımlanan ana yer.
  • containingPlaces: Birincil hedefin parçası olduğu daha büyük kuruluşlar (ör. bir mağazanın bulunduğu alışveriş merkezi).
  • subDestinations: Birincil hedefteki daha ayrıntılı konumlar (örneğin, bir binadaki daireler).
  • entrances: Hedef için belirli giriş ve çıkış noktaları.
  • navigationPoints: Navigasyonun sonlandırılacağı yolun yakınındaki uygun konumlar.
  • arrivalSummary: Varış konusunda yardımcı olmak için yapay zeka destekli analizler. Yapay zeka destekli özetler başlıklı makaleyi inceleyin.
  • landmarks: Kullanıcıların varış noktasının çevresini anlamasına yardımcı olacak, yakındaki önemli yerler.

Tüm yanıt alanlarıyla ilgili ayrıntılı bilgi için API Referansı'na bakın.

Yanıt biçimi

SearchDestinations, aşağıdaki JSON biçiminde bir SearchDestinationsResponse döndürür:

{
  "destinations": [
    {
      "primary": {
        "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w",
        "displayName": {
          "text": "Arby's",
          "languageCode": "en"
        },
        "primaryType": "fast_food_restaurant",
        "types": [
          "fast_food_restaurant",
          "sandwich_shop",
          "deli",
          "american_restaurant",
          "meal_takeaway",
          "restaurant",
          "food_store",
          "food",
          "point_of_interest",
          "store",
          "establishment"
        ],
        "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA",
        "postalAddress": {
          "regionCode": "US",
          "languageCode": "en",
          "postalCode": "94087",
          "administrativeArea": "CA",
          "locality": "Sunnyvale",
          "addressLines": [
            "601 S Bernardo Ave"
          ]
        },
        "structureType": "BUILDING",
        "location": {
          "latitude": 37.3734545,
          "longitude": -122.05693269999998
        },
        "displayPolygon":
 { ... } {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.056930138027,
                37.3735253692531
              ],
              [
                -122.056960139391,
                37.3735372663597
              ],
              [
                -122.056994129366,
                37.3734828786847
              ],
              [
                -122.056969677395,
                37.3734731161089
              ],
              [
                -122.057061762447,
                37.3733261309656
              ],
              [
                -122.056979388817,
                37.3732935577128
              ],
              [
                -122.056798860285,
                37.3735818838642
              ],
              [
                -122.056875858081,
                37.3736121235316
              ],
              [
                -122.056930138027,
                37.3735253692531
              ]
            ]
          ]
        }

      },
      "containingPlaces": [
        {
          "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw",
          "displayName": {
            "text": "Cherry Chase Shopping Center",
            "languageCode": "en"
          },
          "primaryType": "shopping_mall",
          "types": [
            "shopping_mall",
            "point_of_interest",
            "establishment"
          ],
          "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA",
          "postalAddress": {
            "regionCode": "US",
            "languageCode": "en",
            "postalCode": "94087-1020",
            "administrativeArea": "CA",
            "locality": "Sunnyvale",
            "addressLines": [
              "663 S Bernardo Ave"
            ]
          },
          "structureType": "GROUNDS",
          "location": {
            "latitude": 37.3731231,
            "longitude": -122.0578211
          },
          "displayPolygon":
 { ... } {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  -122.057112227103,
                  37.3714618008523
                ],
                [
                  -122.057076849821,
                  37.3715743611411
                ],
                [
                  -122.056963607756,
                  37.3719081793948
                ],
                [
                  -122.056865279559,
                  37.3722026053835
                ],
                [
                  -122.056687872374,
                  37.3727258358476
                ],
                [
                  -122.056580005889,
                  37.3730511370747
                ],
                [
                  -122.056498845827,
                  37.3732994782583
                ],
                [
                  -122.056338259713,
                  37.3737878663325
                ],
                [
                  -122.056618678291,
                  37.373887693582
                ],
                [
                  -122.056912102521,
                  37.3740010327191
                ],
                [
                  -122.057532418159,
                  37.3742476426462
                ],
                [
                  -122.057673926626,
                  37.3742441740031
                ],
                [
                  -122.057735663106,
                  37.3742328516943
                ],
                [
                  -122.057766531332,
                  37.3742220604378
                ],
                [
                  -122.057797572967,
                  37.37420520725
                ],
                [
                  -122.057828267759,
                  37.3741852342085
                ],
                [
                  -122.058060299297,
                  37.3740060842535
                ],
                [
                  -122.058199726081,
                  37.3737861673422
                ],
                [
                  -122.05836707267,
                  37.373524542556
                ],
                [
                  -122.058569622393,
                  37.3732018598683
                ],
                [
                  -122.0587638478,
                  37.3728890198039
                ],
                [
                  -122.058934661823,
                  37.3726036257774
                ],
                [
                  -122.059164956851,
                  37.3722498383629
                ],
                [
                  -122.058997784906,
                  37.3721804442035
                ],
                [
                  -122.057936479838,
                  37.3717605636234
                ],
                [
                  -122.057495827092,
                  37.3715860151634
                ],
                [
                  -122.057112227103,
                  37.3714618008523
                ]
              ]
            ]
          }

        }
      ],
      "landmarks":
 [ ... ] [
        {
          "place": {
            "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "florist",
              "butcher_shop",
              "deli",
              "bakery",
              "food_delivery",
              "supermarket",
              "market",
              "food_store",
              "food",
              "point_of_interest",
              "store",
              "establishment"
            ],
            "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "639 S Bernardo Ave"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3727912,
              "longitude": -122.0581172
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 158.65607,
          "travelDistanceMeters": 131.16699
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "types": [
              "fast_food_restaurant",
              "restaurant",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1028",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1241 W El Camino Real"
              ]
            },
            "structureType": "BUILDING",
            "location": {
              "latitude": 37.3746764,
              "longitude": -122.05708860000001
            },
            "displayPolygon":
 { ... } {
              "type": "Polygon",
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ]
            }

          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 87.34801,
          "travelDistanceMeters": 214.08084
        },
        {
          "place": {
            "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg",
            "displayName": {
              "text": "Chase Bank",
              "languageCode": "en"
            },
            "primaryType": "bank",
            "types": [
              "bank",
              "atm",
              "finance",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1234 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.373579,
              "longitude": -122.05752700000001
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 61.182194,
          "travelDistanceMeters": 63.075645
        },
        {
          "place": {
            "place": "places/ChIJlbIO1Oi2j4ARp17Uf24xkHk",
            "displayName": {
              "text": "Madras Café",
              "languageCode": "en"
            },
            "primaryType": "indian_restaurant",
            "types": [
              "indian_restaurant",
              "coffee_shop",
              "cafe",
              "restaurant",
              "food_store",
              "food",
              "point_of_interest",
              "store",
              "establishment"
            ],
            "formattedAddress": "Madras Café, 1177 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1026",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1177 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743,
              "longitude": -122.0549333
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Madras Café",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 204.45102,
          "travelDistanceMeters": 235.12041
        }
      ]
,
      "entrances": [
        {
          "location": {
            "latitude": 37.373531299999996,
            "longitude": -122.05694519999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "UNKNOWN"
          ]
        }
      ]
    }
  ]
}

Gerekli parametreler

  • Hedef için aranacak adresi, yeri veya konumu belirten aşağıdaki 3 parametreden biri API isteğinde olmalıdır:
    • addressQuery: Aranacak adres.
    • place: Aranacak yerin yer kimliği.
    • locationQuery - Aranacak konumun enlem ve boylam koordinatları.

  • FieldMask

    Yanıt alan maskesi oluşturarak yanıtta döndürülecek alanların listesini belirtin. Yanıt alan maskesini, $fields veya fields URL parametresini ya da X-Goog-FieldMask HTTP üst bilgisini kullanarak yönteme iletin. Örneğin, aşağıdaki istek yalnızca birincil hedefin girişlerini, gezinme noktalarını ve yer kimliğini döndürür.

      curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
    -H "X-Goog-Api-Key: API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \
    https://geocode.googleapis.com/v4alpha/geocode/destinations

    Yanıtta varsayılan olarak döndürülen alanların listesi yoktur. Alan maskesini atlarsanız yöntem hata döndürür. Tüm alanları döndürmek için alan maskesini * olarak ayarlayın. Daha fazla bilgi için Döndürülecek alanları seçme bölümüne bakın.

İsteğe bağlı parametreler

  • travelModes

    Hangi navigationPoints türlerinin döndürüleceğini belirtir. Diğer seyahat modlarına ait gezinme noktaları filtrelenir. travelModes ayarlanmamışsa tüm ulaşım şekillerinin gezinme noktaları döndürülebilir.

  • languageCode

    Sonuçların döndürüleceği dil.

    • Desteklenen dillerin listesini inceleyin. Google, desteklenen dilleri sık sık güncellediği için bu liste kapsamlı olmayabilir.
    • languageCode sağlanmazsa API varsayılan olarak en değerini kullanır. Geçersiz bir dil kodu belirtirseniz API INVALID_ARGUMENT hatası döndürür.
    • API, hem kullanıcı hem de yerel halk için okunabilir bir açık adres sağlamak üzere elinden geleni yapar. Bu hedefi gerçekleştirmek için tercih edilen dili dikkate alarak sokak adreslerini yerel dilde döndürür. Gerekirse adresler, kullanıcı tarafından okunabilir bir alfabeye çevrilir. Diğer tüm adresler tercih edilen dilde döndürülür. Adres bileşenlerinin tümü, ilk bileşenden seçilen aynı dilde döndürülür.
    • Ad, tercih edilen dilde kullanılamıyorsa API en yakın eşleşmeyi kullanır.
    • Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç kümesi ve bu sonuçların döndürülme sırası üzerinde küçük bir etkiye sahiptir. Coğrafi kodlayıcı, kısaltmaları dile bağlı olarak farklı şekilde yorumlar. Örneğin, sokak türlerinin kısaltmaları veya bir dilde geçerli olup başka bir dilde geçerli olmayan eş anlamlılar.

  • regionCode

    Bölge kodu, iki karakterli CLDR kodu değeri olarak. Varsayılan değer yoktur. Çoğu CLDR kodu, ISO 3166-1 kodlarıyla aynıdır.

    Bir adresin coğrafi kodlaması yapılırken (ileri coğrafi kodlama) bu parametre, hizmetten gelen sonuçları belirtilen bölgeyle sınırlayabilir ancak tamamen kısıtlayamaz. Bir konum veya yer coğrafi olarak kodlanırken (tersine coğrafi kodlama veya yer coğrafi kodlama), bu parametre adresi biçimlendirmek için kullanılabilir. Bu parametre, her durumda geçerli yasaya göre sonuçları etkileyebilir.

  • placeFilter

    locationQuery Arama sonuçlarını, yalnızca binalar olan veya net adresleri olan hedefleri döndürme gibi gereksinimlerinizi karşılayacak şekilde filtrelemenizi sağlar.

    Yapısal ayrıntı düzeyine göre filtreleme

    structureType filtresi, sorgu tarafından döndürülen yapı türlerini belirtmenize olanak tanır:

    • Binaları Ayırma: Haritada bina ana hatlarını göstermek veya belirli bir yapı hakkında ayrıntılı bilgi edinmek için "structureType": "BUILDING" simgesini kullanın.
    • Tesisleri Anlama: Birincil sonucun genel alan olduğundan emin olmak için "structureType": "GROUNDS" kullanın. Bu özellik, üniversite kampüsleri veya alışveriş merkezleri gibi daha büyük alanlar için sorgu gönderirken faydalıdır.
    • Birimlere/Bölümlere Odaklanma: Bir binadaki bölümleri tanımlamak için "structureType": "SECTION" kullanın.

    Faydalı adresler sağlama

    Bazı yerlerin açık adresleri yoktur. addressability filtresi, sonuçlarınızdaki adreslerin kalitesini kontrol etmenize yardımcı olur:

    • Net Bir Birincil Adres Gerektir: Ana hedef sonucunun her zaman sokak düzeyinde bir adresi veya adı olmasını sağlamak için "addressability": "PRIMARY" kullanın. Bu, net bir adresin önemli olduğu gezinme veya görüntüleme amaçları için yararlıdır.
    • Alt Hedeflerde Adreslere İzin Ver: Birincil yerin adresi olmayabilir ancak içindeki birimlerin (ör. bir binadaki daireler) adresi olabilir. Bu gibi durumlarda "addressability": "WEAK", en azından birincil yerin veya alt hedeflerinden birinin adresinin olmasını sağlar.
    • Herhangi bir sonuç: Adres varlığı kullanım alanınızla alakalı değilse "addressability": "ANY" kullanın.
    Örnek: Adreslenebilir Binalar İçin Filtreleme 
    curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "PRIMARY"
    }
  },
  "languageCode": "en"
}' \\
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\
-H "X-Goog-FieldMask: place" \\
https://geocode.googleapis.com/v4alpha/geocode/destinations

Geri bildirim

Bu, Geocoding API'nin deneysel bir uç noktasıdır. geocoding-feedback-channel@google.com adresinden geri bildirimlerinizi bekliyoruz.