wyszukiwać miejsca docelowe,

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

A Destination to konkretna lokalizacja lub miejsce, do którego użytkownik chce dotrzeć lub w którego kierunku chce się poruszać. Destination zawiera też zbiór informacji związanych z lokalizacją lub miejscem, takich jak punkty nawigacyjne, punkty orientacyjne, wejścia i kontury budynków.

Metoda SearchDestinations interfejsu Geocoding API umożliwia pobieranie szczegółowych informacji o różnych miejscach docelowych na podstawie różnych kryteriów wejściowych, takich jak adres, identyfikator miejsca lub współrzędne geograficzne.

Prośba o wyszukanie miejsc docelowych

Żądanie wyszukiwania miejsc docelowych to żądanie HTTP POST wysyłane na adres URL w formacie:

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

Przekaż wszystkie parametry w treści żądania JSON lub w nagłówkach w ramach żądania POST. Na przykład:

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/v4/geocode/destinations

Lokalizację, w której chcesz wyszukać miejsce docelowe, możesz określić na 3 sposoby:

  • Adres
  • Identyfikator miejsca
  • Współrzędne geograficzne

Wyszukiwanie miejsca docelowego według adresu

Adres możesz podać jako nieuporządkowany ciąg znaków. Geokodowanie adresu nie rozpoznaje współrzędnych szerokości i długości geograficznej ani innych nieuporządkowanych ciągów znaków, które nie reprezentują adresu. Żądania używające takich ciągów nie są obsługiwane i mogą powodować błędy lub nieokreślone zachowanie. Przykłady nieobsługiwanych zapytań:

Typ zapytania Przykład
Współrzędne szerokości i długości geograficznej. Zamiast tego użyj zapytania o lokalizację. "37.422131,-122.084801"
Zbyt wiele pojęć lub ograniczeń, np. nazwy wielu miejsc, dróg lub miast w jednym zapytaniu. "Market Street San Francisco San Jose Airport"
Elementy adresu pocztowego nie są widoczne w Mapach Google. "C/O Jan Kowalski, ul. Główna 123"
"Skr. poczt. 13, Warszawa"
Nazwy firm, sieci lub kategorii połączone z lokalizacjami, w których te podmioty nie są dostępne „Tesco w pobliżu Dallas w Teksasie”
Niejednoznaczne zapytania z wieloma interpretacjami „Oddanie ładowarki”
nazwy historyczne, które nie są już używane; „Middlesex, Wielka Brytania”
Elementy lub intencje niezwiązane z geoprzestrzenią „Ile łodzi jest w porcie Ventura?”
Nieoficjalne lub wymyślone nazwy „The Jenga”
„The Helter Skelter”
Duże jednostki polityczne (miasta, stany, kraje) "Nowy Jork"
"Kalifornia"
"USA"
Trasy bez konkretnych adresów „1st Ave., Nowy Jork, NY”
„I-95” 
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/v4/geocode/destinations

lub jako postalAddress:

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/v4/geocode/destinations

Format postalAddress jest zwykle używany podczas przetwarzania komponentów adresu przechwyconych w formularzu HTML.

Wyszukiwanie miejsca docelowego według identyfikatora miejsca

Możesz pobrać miejsce docelowe, podając identyfikator miejsca:

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/v4/geocode/destinations

Obsługiwane identyfikatory miejsc

Metoda Search Destinations działa najlepiej z identyfikatorami miejsc, które reprezentują konkretne miejsca docelowe, do których można dotrzeć. Identyfikatory miejsc dla typów takich jak establishment, point_of_interest, premise, street_address i subpremise są ogólnie obsługiwane. Identyfikatory miejsc, które nie reprezentują konkretnych lokalizacji, np. określone na podstawie zakresów adresów (np. „ul. Główna 10–20”), odcinków trasy bez konkretnego numeru lub plus kodów, nie są obsługiwane. Identyfikatory miejsc dla wyników, które obejmują zbyt duży obszar (np. „Ocean Spokojny”), również nie są obsługiwane.

Korzystanie z autouzupełniania (nowego) w przypadku miejsc docelowych wyszukiwania

Aby zapewnić zgodność, użyj Autouzupełniania (nowego) do wyszukiwania identyfikatorów miejsc, które będą używane w wyszukiwaniu miejsc docelowych. Jeśli korzystasz z Autouzupełniania (nowego), wyniki należy filtrować według typu za pomocą parametru includedPrimaryTypes. Identyfikatory miejsc zwracane przez Autocomplete (New) z użyciem tego zalecanego filtra są obsługiwane przez Search Destinations:

"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]

W żądaniu Autouzupełniania (nowego) nie ustawiaj flagi include_pure_service_area_businesses na true.

Wyszukiwanie miejsca docelowego według lokalizacji

Możesz wyszukać miejsce docelowe, podając współrzędne geograficzne: szerokość i długość geograficzną.

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/v4/geocode/destinations

Wysyłanie żądania za pomocą protokołu OAuth

Interfejs Geocoding API w wersji 4 obsługuje OAuth 2.0 na potrzeby uwierzytelniania. Aby używać protokołu OAuth z interfejsem Geocoding API, tokenowi OAuth należy przypisać odpowiedni zakres. Geocoding API obsługuje te zakresy do użycia z metodą Destinations:

  • https://www.googleapis.com/auth/maps-platform.geocode – używaj ze wszystkimi metodami Geocoding API.

Możesz też użyć ogólnego zakresu https://www.googleapis.com/auth/cloud-platform dla wszystkich metod interfejsu Geocoding API. Ten zakres jest przydatny podczas programowania, ale nie w środowisku produkcyjnym, ponieważ jest to zakres ogólny, który umożliwia dostęp do wszystkich metod.

Więcej informacji i przykładów znajdziesz w artykule Korzystanie z OAuth.

Odpowiedź dotycząca miejsc docelowych wyszukiwania

Odpowiedź interfejsu Search Destinations zawiera bogaty, hiperlokalny kontekst dotyczący lokalizacji.

Obiekty PlaceView w odpowiedzi Search Destinations (takie jak primary, elementy w containingPlaces i landmarks) używają pól do wskazania typu miejsca:

  • types: tablica ciągów znaków wskazujących typy miejsca.
  • primaryType: ciąg znaków wskazujący główny typ miejsca.

Możliwe wartości ciągów znaków dla parametrów types i primaryType pochodzą z tabel A i B na stronie Typy miejsc (nowe).

W tej sekcji opisujemy najważniejsze pola odpowiedzi. Szczegółowe informacje o wszystkich polach odpowiedzi znajdziesz w dokumentacji API.

primary

Główne miejsce zidentyfikowane przez zapytanie w żądaniu.

addressComponents

Tablica zawierająca oddzielne komponenty, które mają zastosowanie do tego adresu.

Każdy komponent adresu zawiera zwykle te pola:

  • types[] to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.
  • longText to pełny opis tekstowy lub nazwa komponentu adresu zwracanego przez geokoder.
  • shortText to skrócona nazwa tekstowa komponentu adresu, jeśli jest dostępna. Na przykład komponent adresu dla stanu Alaska może mieć longText „Alaska” i shortText „AK” z dwuliterowym skrótem pocztowym.
  • languageCode to język używany do formatowania tego komponentu w notacji CLDR.

containingPlaces

Większe obiekty, których częścią jest główne miejsce docelowe (np. centrum handlowe, w którym znajduje się sklep).

subDestinations

bardziej szczegółowe lokalizacje w obrębie głównego miejsca docelowego (np. mieszkania w budynku).

entrances

Obiekty w tablicy entrances[] mają te pola:

  • location

    Pojedyncza para współrzędnych geograficznych (szerokość/długość geograficzna), która określa lokalizację punktu wejścia i wyjścia z miejsca.

  • entrance_tags[]

    Tablica tagów wejścia opisujących cechy wejścia. Obsługiwana jest ta wartość:

    • "PREFERRED"

    Wskazuje, że to wejście prawdopodobnie zapewnia fizyczny dostęp do zwróconego miejsca. Miejsce może mieć kilka preferowanych wejść. Jeśli wejście nie ma tego tagu, oznacza to, że znajduje się ono fizycznie w tym samym budynku, ale niekoniecznie zapewnia dostęp do danego miejsca.

    Jeśli na przykład zwrócone miejsce to restauracja w centrum handlowym, wejścia "PREFERRED" będą prowadzić do samej restauracji, a inne zwrócone wejścia będą prowadzić do budynku, np. do innych restauracji w centrum handlowym.

    Jeśli zwrócone miejsce jest budynkiem, "PREFERRED" wejścia będą prowadzić do „głównej” części budynku. Na przykład w centrum handlowym wejścia "PREFERRED" będą prowadzić do głównego foyer, ale jeśli wejście prowadzi tylko do sklepu z boku budynku, nie będzie to wejście "PREFERRED".

  • streetViewThumbnail i streetViewAnnotation

    Parametry interfejsu Street View Static API, które umożliwiają wyświetlanie odpowiednich zdjęć tych lokalizacji. Więcej informacji o tych polach

structureType

Typ struktury, którą reprezentuje to miejsce.

  • POINT

    Lokalizacja punktu.

  • SECTION

    Podsekcja budynku.

  • BUILDING

    Budynek.

  • GROUNDS

    Duży obszar, który zwykle obejmuje kilka budynków, np. kampus uniwersytecki, kompleks apartamentów lub centrum handlowe.

Pole navigationPoints w odpowiedzi interfejsu Geocoding API zawiera listę punktów, które są przydatne podczas nawigowania do miejsca. Powinny być używane jako punkty początkowe lub końcowe podczas wyznaczania trasy w sieci dróg z miejsca lub do miejsca.

Każdy punkt nawigacyjny zawiera te wartości:

  • navigationPointToken to token zawierający informacje kontekstowe w polu navigationPoints. Możesz wysłać ten token do interfejsów API wyznaczania trasy i nawigacji, aby ulepszyć wyznaczanie trasy i wrażenia kierowcy w aplikacji. Więcej informacji znajdziesz w artykule Wyznaczanie trasy za pomocą tokenów punktów nawigacyjnych.
  • location zawiera wartość szerokości i długości geograficznej punktu nawigacyjnego. Ta lokalizacja będzie zawsze bardzo blisko sieci dróg i będzie stanowić idealny punkt zatrzymania lub punkt początkowy nawigacji do i z danego miejsca. Punkt jest celowo nieco przesunięty względem osi drogi, aby wyraźnie zaznaczyć stronę drogi, po której znajduje się miejsce.
  • travelModes to lista środków transportu, z których można dotrzeć do punktu nawigacyjnego:
    • "DRIVE" to tryb podróży odpowiadający wskazówkom dojazdu.
    • "WALK" to środek transportu odpowiadający trasie pieszej.
  • usages to lista zastosowań obsługiwanych przez punkt nawigacyjny. Zastosowania mogą być:
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

W przypadku odbiorów i nadawania użyj punktu nawigacyjnego, w którym tryb podróży to DRIVE, a użycie to PICKUP lub DROPOFF. Jeśli punkty odbioru lub dostawy są niedostępne, użyj najwyższego punktu nawigacji samochodowej.

  • altitude_meters zawiera wysokość punktu nawigacyjnego w metrach względem elipsoidy WGS-84. W przypadku fragmentów drogi ułożonych pionowo użyj pola altitude_meters, aby wybrać najlepszy fragment drogi, do którego system ma nawigować.

landmarks

Ważne miejsca w pobliżu, które pomogą użytkownikom poznać okolicę miejsca docelowego.

Każdy punkt orientacyjny zawiera te pola:

  • place to obiekt PlaceView, który reprezentuje ten punkt orientacyjny.
  • relationalDescription to zrozumiały dla człowieka opis relacji między miejscem docelowym a punktem orientacyjnym, np. „W pobliżu Empire State Building” lub „Naprzeciwko Białego Domu”.
  • tags[] to tablica tagów opisujących, jak można wykorzystać punkt orientacyjny w kontekście miejsca docelowego:
    • "ADDRESS": znane miejsce w okolicy, które może służyć do określenia ogólnej lokalizacji miejsca docelowego.
    • "ARRIVAL": miejsce, które może pomóc dotrzeć do celu, przydatne do nawigacji w pobliżu miejsca docelowego.
  • straightLineDistanceMeters to odległość w metrach w linii prostej od tego punktu orientacyjnego do miejsca docelowego.
  • travelDistanceMeters to odległość w metrach od tego punktu orientacyjnego do miejsca docelowego.

arrivalSummary

Statystyki oparte na AI, które pomagają w dotarciu na miejsce. Zobacz podsumowania oparte na AI.

parkingOptions

Szczegółowe informacje o parkingu.

Format odpowiedzi

SearchDestinations zwraca obiekt SearchDestinationsResponse w tym formacie JSON:

{
  "destinations": [
    {
      "primary": {
        "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w",
        "displayName": {
          "text": "Arby's",
          "languageCode": "en"
        },
        "primaryType": "fast_food_restaurant",
        "types": [
          "fast_food_restaurant",
          "sandwich_shop",
          "deli",
          "meal_takeaway",
          "food_delivery",
          "american_restaurant",
          "restaurant",
          "food_store",
          "store",
          "food",
          "point_of_interest",
          "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/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
            }
          },
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 61.182193756103516,
          "travelDistanceMeters": 63.075645446777344
        },
        {
          "place": {
            "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "butcher_shop",
              "florist",
              "deli",
              "supermarket",
              "bakery",
              "food_delivery",
              "market",
              "manufacturer",
              "food_store",
              "store",
              "food",
              "service",
              "point_of_interest",
              "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
            }
          },
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 158.65606689453125,
          "travelDistanceMeters": 131.1669921875
        },
        {
          "place": {
            "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk",
            "displayName": {
              "text": "Oil Changers",
              "languageCode": "en"
            },
            "types": [
              "car_repair",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1240 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743054,
              "longitude": -122.0584272
            }
          },
          "relationalDescription": {
            "text": "Down the road from Oil Changers",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL"
          ],
          "straightLineDistanceMeters": 140.52459716796875,
          "travelDistanceMeters": 143.24220275878906
        },
        {
          "place": {
            "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0",
            "displayName": {
              "text": "Apni Mandi Farmers Market Sunnyvale",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "cake_shop",
              "supermarket",
              "asian_grocery_store",
              "indian_restaurant",
              "meal_takeaway",
              "bakery",
              "manufacturer",
              "wholesaler",
              "restaurant",
              "food_store",
              "store",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1056",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1111 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3737199,
              "longitude": -122.0522958
            }
          },
          "relationalDescription": {
            "text": "Near Apni Mandi Farmers Market Sunnyvale",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 410.37435913085938,
          "travelDistanceMeters": 479.49893188476562
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "primaryType": "chicken_restaurant",
            "types": [
              "chicken_restaurant",
              "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": {
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ],
              "type": "Polygon"
            }
          },
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 87.348007202148438,
          "travelDistanceMeters": 214.08084106445312
        }
      ],
      "entrances": [
        {
          "location": {
            "latitude": 37.3735328,
            "longitude": -122.05694879999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4",
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "PARKING"
          ]
        }
      ]
    }
  ]
}

Wymagane parametry

  • W żądaniu do interfejsu API musi być podany jeden z tych 3 parametrów, który określa adres, miejsce lub lokalizację, w której ma być wyszukiwane miejsce docelowe:
    • addressQuery – adres, który chcesz wyszukać.
    • place – identyfikator miejsca, które chcesz wyszukać.
    • locationQuery – współrzędne geograficzne wyszukiwanej lokalizacji.

  • FieldMask

    Określ listę pól, które mają zostać zwrócone w odpowiedzi, tworząc maskę pola odpowiedzi. Przekaż maskę pola odpowiedzi do metody, używając parametru adresu URL $fields lub fields albo nagłówka HTTP X-Goog-FieldMask. Na przykład poniższe żądanie zwróci tylko wejścia, punkty nawigacyjne i identyfikator miejsca głównego miejsca docelowego.

      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/v4/geocode/destinations

    W odpowiedzi nie ma domyślnej listy zwracanych pól. Jeśli pominiesz maskę pola, metoda zwróci błąd. Ustaw maskę pola na *, aby zwrócić wszystkie pola. Więcej informacji znajdziesz w artykule Wybieranie pól do zwrócenia.

Parametry opcjonalne

  • travelModes

    Określa typy navigationPoints, które mają być zwracane. Punkty nawigacyjne dla innych środków transportu zostaną odfiltrowane. Jeśli parametr travelModes nie jest ustawiony, mogą być zwracane punkty nawigacyjne wszystkich środków transportu.

  • languageCode

    Język, w którym mają być zwracane wyniki.

    • Zobacz listę obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być wyczerpująca.
    • Jeśli nie podasz parametru languageCode, interfejs API domyślnie użyje języka i pisma lokalnego. Jeśli podasz nieprawidłowy kod języka, API zwróci błąd INVALID_ARGUMENT.
    • Interfejs API stara się podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i miejscowych. Aby osiągnąć ten cel, zwraca adresy pocztowe w języku lokalnym, w razie potrzeby transliterowane na pismo czytelne dla użytkownika, z uwzględnieniem preferowanego języka. Wszystkie inne adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego komponentu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API używa najbliższego dopasowania.
    • Preferowany język ma niewielki wpływ na zbiór wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one zwracane. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym.

  • regionCode

    Kod regionu jako dwuznakowy kod CLDR. Nie ma wartości domyślnej. Większość kodów CLDR jest identyczna z kodami ISO 3166-1.

    Podczas geokodowania adresu, czyli geokodowania do przodu, ten parametr może wpływać na wyniki usługi, ale nie może ich w pełni ograniczać do określonego regionu. Tego parametru można używać do formatowania adresu podczas geokodowania lokalizacji lub miejsca, odwrotnego geokodowania lub geokodowania miejsca. We wszystkich przypadkach ten parametr może wpływać na wyniki zgodnie z obowiązującymi przepisami.

  • placeFilter

    Umożliwia filtrowanie wyników wyszukiwania locationQuery pod kątem określonych wymagań, np. zwracanie tylko miejsc docelowych, które są budynkami, lub tylko tych, które mają dokładne adresy.

    Filtrowanie według szczegółowości strukturalnej

    Filtr structureType umożliwia określenie rodzaju struktur zwracanych przez zapytanie:

    • Wyodrębnianie budynków: użyj ikony "structureType": "BUILDING", aby wyświetlić zarysy budynków na mapie lub uzyskać szczegółowe informacje o konkretnym obiekcie.
    • Zrozumienie kompleksów: użyj "structureType": "GROUNDS", aby upewnić się, że głównym wynikiem jest cały teren. Jest to przydatne, gdy wysyłasz zapytania o większe obszary, takie jak kampusy uniwersyteckie czy centra handlowe.
    • Skupienie się na jednostkach/sekcjach: użyj "structureType": "SECTION", aby zidentyfikować sekcje w budynku.

    Zapewnianie przydatnych adresów

    Nie wszystkie miejsca mają jasne adresy na poziomie ulicy. Filtr addressability pomaga kontrolować jakość adresów w wynikach:

    • Wymagaj wyraźnego adresu podstawowego: aby główny wynik docelowy zawsze zawierał adres lub nazwę na poziomie ulicy, użyj "addressability": "PRIMARY". Jest to przydatne do celów nawigacji lub wyświetlania, gdy kluczowe jest podanie dokładnego adresu.
    • Zezwalaj na adresy w miejscach podrzędnych: w przypadkach, gdy miejsce główne może nie mieć adresu, ale mają go jednostki w nim (np. mieszkania w budynku), "addressability": "WEAK" zapewnia, że co najmniej miejsce główne lub jedno z jego miejsc podrzędnych ma adres.
    • Dowolny wynik: jeśli obecność adresu nie jest istotna w Twoim przypadku użycia, użyj "addressability": "ANY". Jest to wysoce zalecane, gdy potrzebujesz tylko atrybutów geometrycznych, takich jak kontury budynków i punkty nawigacyjne, ponieważ zwiększa to dokładność wyników.
    Przykład: filtrowanie budynków z adresem 
    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/v4/geocode/destinations