wyszukiwać miejsca docelowe,

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Destination to konkretna lokalizacja lub miejsce, do którego użytkownik chce dotrzeć lub do którego chce nawigować. 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 szerokości i długości geograficznej.

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ń, takich jak 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, Teksas”
niejednoznaczne zapytania, które można interpretować na wiele sposobów; „Punkt odbioru ładowarek”
nazwy historyczne, które nie są już używane; "Middlesex United Kingdom"
Elementy lub intencje niegeoprzestrzenne „Ile łodzi jest w porcie Ventura?”
nieoficjalne lub niestandardowe nazwy, „Jenga”
„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. wywnioskowane z zakresów adresów (np. „ul. Główna 10–20”), odcinki trasy bez konkretnego numeru lub kody Plus, 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.

Używanie autouzupełniania (nowego) z miejscami docelowymi wyszukiwania

Aby zapewnić zgodność, użyj autouzupełniania (nowego) do znajdowania identyfikatorów miejsc do użycia z miejscami docelowymi wyszukiwania. Jeśli używasz autouzupełniania (nowego), wyniki należy filtrować według typu za pomocą parametru includedPrimaryTypes. Identyfikatory miejsc zwracane przez autouzupełnianie (nowe) z użyciem tego zalecanego filtra są obsługiwane przez wyszukiwanie miejsc docelowych:

"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

Geocoding API w wersji 4 obsługuje uwierzytelnianie OAuth 2.0. 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żywać ogólnego zakresu https://www.googleapis.com/auth/cloud-platform we wszystkich metodach 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łady znajdziesz w artykule o korzystaniu z protokołu OAuth.

Odpowiedź dotycząca miejsc docelowych wyszukiwania

Odpowiedź z 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ągu znaków dla types i primaryType pochodzą z tabeli A i tabeli B na stronie Typy miejsc (nowe).

W tej sekcji opisano 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ć wartość longText „Alaska” i wartość shortText „AK” (dwuliterowy skrót pocztowy).
  • 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:

  • displayName

    Obiekt LocalizedText zawierający zrozumiałą dla człowieka nazwę wejścia (np. "South Bernardo Avenue" lub "5th Avenue"), jeśli jest dostępna.

  • location

    Pojedyncza para współrzędnych szerokości i długości geograficznej, która określa lokalizację punktu wejścia i wyjścia z miejsca.

  • entrance_tags[]

    Tablica tagów wejścia, która opisuje 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, wejścia "PREFERRED" 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 Street View Static API, które umożliwiają wyświetlanie odpowiednich zdjęć dla 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 geokodowania zawiera listę punktów, które są przydatne do nawigacji 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ści 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 wysiadania są niedostępne, użyj górnego 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, które opisują, 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 w dotarciu do celu, przydatne do nawigacji, gdy jesteś już blisko celu.
  • straightLineDistanceMeters to odległość w linii prostej od tego punktu orientacyjnego do miejsca docelowego w metrach.
  • travelDistanceMeters to odległość pieszo od tego punktu orientacyjnego do miejsca docelowego w metrach.

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": [
        {
          "displayName": {
            "text": "South Bernardo Avenue",
            "languageCode": "en"
          },
          "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 znajdować się jeden z tych 3 parametrów, który określa adres, miejsce lub lokalizację, w której ma zostać wyszukane 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. Aby zwrócić wszystkie pola, ustaw maskę pola na *. Więcej informacji znajdziesz w artykule Wybieranie pól do zwrócenia.

Parametry opcjonalne

  • travelModes

    Określa, które typy navigationPoints 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, interfejs API zwróci błąd INVALID_ARGUMENT.
    • Interfejs API stara się podać adres, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. 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 zestaw wyników, które interfejs API zwraca, oraz na kolejność, w jakiej są 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 (geokodowanie bezpośrednie) ten parametr może wpływać na wyniki usługi w określonym regionie, ale nie ogranicza ich całkowicie. 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 zgodnie z Twoimi wymaganiami, np. zwracanie tylko miejsc docelowych, które są budynkami, lub tylko miejsc docelowych, które mają dokładne adresy.

    Filtrowanie według szczegółowości strukturalnej

    Filtr structureType pozwala określić rodzaj struktur zwracanych przez zapytanie:

    • Izolowanie budynków: użyj "structureType": "BUILDING", aby wyświetlić kontury budynków na mapie lub uzyskać szczegółowe informacje o konkretnej strukturze.
    • 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 jednoznacznego adresu głównego: aby mieć pewność, że główny wynik miejsca docelowego zawsze zawiera adres na poziomie ulicy lub nazwę, użyj "addressability": "PRIMARY". Jest to przydatne do nawigacji lub wyświetlania, gdy kluczowe znaczenie ma dokładny adres.
    • 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". Zdecydowanie zalecamy to rozwiązanie, gdy potrzebujesz tylko atrybutów geometrycznych, takich jak kontury budynków i punkty nawigacyjne, ponieważ zwiększa ono dokładność tych 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