wyszukiwać miejsca docelowe,

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

A Destination odnosi się do konkretnej lokalizacji lub miejsca, do którego użytkownik chce dotrzeć lub do którego chce się kierować. A Destination obejmuje też zbiór informacji związanych z lokalizacją lub miejscem, takich jak punkty nawigacyjne, punkty orientacyjne, wejścia i obrysy 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.

Żądanie wyszukiwania miejsc docelowych

Żądanie wyszukiwania miejsc docelowych to żądanie HTTP POST wysyłane na adres URL w tym 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 nieustrukturyzowany ciąg znaków. Geokodowanie adresu nie rozwiązuje współrzędnych szerokości i długości geograficznej ani innych nieustrukturyzowanych ciągów znaków, które nie reprezentują adresu. Żądania używające takich ciągów znaków nie są obsługiwane i mogą prowadzić do odpowiedzi z błędem lub nieokreślonego zachowania. Przykłady nieobsługiwanych zapytań:

Typ zapytania Przykład
Współrzędne geograficzne. 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, które nie są reprezentowane w Mapach Google. „C/O John Smith 123 Main Street”
„P.O. Box 13 San Francisco”
Nazwy firm, sieci lub kategorii połączone z lokalizacjami, w których te podmioty nie są dostępne. „Tesco near Dallas, Texas”
Niejednoznaczne zapytania z wieloma interpretacjami. „Charger drop-off”
Historyczne nazwy, które nie są już używane. „Middlesex United Kingdom”
Elementy lub intencje niezwiązane z przestrzenią geograficzną. „How many boats are in Ventura Harbor?”
Nieoficjalne lub niestandardowe nazwy. „The Jenga”
„The Helter Skelter”
Duże podmioty polityczne (miasta, stany, kraje). „New York City”
„California”
„USA”
Trasy bez konkretnych adresów. „1st Ave., NYC, 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

Miejsce docelowe możesz pobrać, 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 najlepiej działa z identyfikatorami miejsc, które reprezentują konkretne, możliwe do nawigacji miejsca docelowe. Identyfikatory miejsc dla typów takich jak establishment, point_of_interest, premise, street_address, i subpremise są na ogół obsługiwane. Identyfikatory miejsc, które nie reprezentują dyskretnych lokalizacji, np. te wywnioskowane z zakresów adresów (np. „10–20 Main St”), odcinki trasy bez konkretnego numeru lub kody plus nie są obsługiwane. Identyfikatory miejsc w przypadku wyników, które są zbyt duże (np. „Ocean Spokojny”), również nie są obsługiwane.

Używanie autouzupełniania (nowego) z metodą Search Destinations

Aby zapewnić zgodność, użyj autouzupełniania (nowego), aby znaleźć identyfikatory miejsc do użycia z metodą Search Destinations. Gdy używasz autouzupełniania (nowego), musisz filtrować wyniki według typu za pomocą includedPrimaryTypes parametru. Identyfikatory miejsc zwracane przez autouzupełnianie (nowe) przy użyciu tego zalecanego filtra są obsługiwane przez metodę Search Destinations:

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

Dodatkowo w żądaniu autouzupełniania (nowego) nie należy ustawiać include_pure_service_area_businesses flagi na true.

Wyszukiwanie miejsca docelowego według lokalizacji

Miejsce docelowe możesz wyszukać, 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ą OAuth

Geocoding API w wersji 4 obsługuje uwierzytelnianie za pomocą OAuth 2.0. Aby używać OAuth z Geocoding API, token OAuth musi mieć przypisany prawidłowy 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 ze wszystkimi metodami 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 Używanie OAuth.

Odpowiedź na żądanie wyszukiwania miejsc docelowych

Odpowiedź na żądanie wyszukiwania miejsc docelowych zawiera bogaty, hiperlokalny kontekst dotyczący lokalizacji.

Obiekty PlaceView w odpowiedzi na żądanie wyszukiwania miejsc docelowych (np. primary, elementy w containingPlaces i landmarks) używają pól do określania typu miejsca:

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

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

W tej sekcji opisujemy najważniejsze pola odpowiedzi. Szczegółowe informacje o wszystkich polach odpowiedzi znajdziesz w dokumentacji interfejsu 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 zwykle zawiera 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 zwrócona 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” przy użyciu dwuliterowego skrótu pocztowego.
  • languageCode to język używany do formatowania tego komponentu w notacji CLDR.

containingPlaces

Większe podmioty, których częścią jest główne miejsce docelowe (np. centrum handlowe zawierające sklep).

subDestinations

Bardziej szczegółowe lokalizacje w głównym miejscu docelowym (np. apartamenty w budynku).

entrances

Obiekty w tablicy entrances[] mają te pola:

  • location

    Pojedyncza para współrzędnych geograficznych, która określa lokalizację punktu wejścia i wyjścia do 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ć wiele preferowanych wejść. Jeśli wejście nie ma tego tagu, oznacza to, że znajduje się fizycznie w tym samym budynku, ale niekoniecznie zapewnia dostęp do miejsca.

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

    Jeśli zwrócone miejsce to sam budynek, wejścia z tagiem "PREFERRED" będą prowadzić do "głównej" części budynku. Na przykład w centrum handlowym wejścia z tagiem "PREFERRED" będą umożliwiać dostęp do głównego holu, ale jeśli wejście umożliwia dostęp tylko do sklepu z boku budynku, nie będzie to wejście z tagiem "PREFERRED".

  • streetViewThumbnail i streetViewAnnotation

    Parametry interfejsu Street View Static API, które umożliwiają wyświetlanie odpowiednich zdjęć w tych lokalizacjach. Dowiedz się więcej o tych polach.

structureType

Typ struktury, którą reprezentuje to miejsce.

  • POINT

    Lokalizacja punktowa.

  • SECTION

    Podsekcja budynku.

  • BUILDING

    Budynek.

  • GROUNDS

    Duży obszar, który zwykle zawiera wiele 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 nawigowania do miejsca. W szczególności należy ich używać jako punktów początkowych lub końcowych podczas wyznaczania trasy w sieci dróg z miejsca lub do niego.

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 poprawić wyznaczanie trasy i nawigację w aplikacji. Więcej informacji znajdziesz w artykule Wyznaczanie trasy za pomocą tokenów punktów nawigacyjnych.
  • location zawiera szerokość i długość geograficzną punktu nawigacyjnego. Ta lokalizacja będzie zawsze bardzo blisko sieci dróg i będzie stanowić idealny punkt zatrzymania lub rozpoczęcia nawigacji do i z miejsca. Punkt jest celowo lekko przesunięty od osi drogi, aby wyraźnie oznaczyć stronę drogi, na której znajduje się miejsce.
  • travelModes to lista trybów podróży, z których można uzyskać dostęp do punktu nawigacyjnego:
    • "DRIVE" to tryb podróży odpowiadający wskazówkom dojazdu.
    • "WALK" to tryb podróży odpowiadający trasie pieszej.
  • usages to lista zastosowań obsługiwanych przez punkt nawigacyjny. Zastosowania mogą być te:
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

W przypadku odbioru i wysiadania użyj punktu nawigacyjnego, w którym tryb podróży to DRIVE, a zastosowanie to PICKUP lub DROPOFF. Jeśli punkty odbioru lub wysiadania są niedostępne, użyj najwyższego punktu nawigacyjnego dla kierowców.

  • altitude_meters zawiera wysokość punktu nawigacyjnego w metrach względem elipsoidy WGS-84. W przypadkach, gdy występują pionowo ułożone odcinki dróg, użyj pola altitude_meters, aby wybrać najlepszy odcinek drogi, do którego ma prowadzić nawigacja.

landmarks

Znane miejsca w pobliżu, które pomagają użytkownikom zrozumieć otoczenie miejsca docelowego.

arrivalSummary

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

parkingOptions

Szczegółowe informacje o parkowaniu.

Format odpowiedzi

Metoda SearchDestinations zwraca 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 ma być wyszukiwany.
    • place – identyfikator miejsca, które ma być wyszukiwane.
    • locationQuery – współrzędne geograficzne lokalizacji, która ma być wyszukiwana.

  • FieldMask

    Określ listę pól, które mają być zwracane w odpowiedzi, tworząc maskę pola odpowiedzi. Przekaż maskę pola odpowiedzi do metody za pomocą parametru URL $fields lub fields, albo za pomocą 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 trybów podróży zostaną odfiltrowane. Jeśli travelModes nie jest ustawiony, można zwrócić punkty nawigacyjne wszystkich trybów podróży.

  • languageCode

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

    • Zobacz listę obsługiwanych języków . Google często aktualizuje listę obsługiwanych języków, więc może ona nie być wyczerpująca.
    • Jeśli parametr languageCode nie zostanie podany, interfejs API domyślnie użyje lokalnego języka i skryptu lokalizacji. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błąd INVALID_ARGUMENT.
    • Interfejs API dokłada wszelkich starań, aby podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby to osiągnąć, zwraca adresy ulic w języku lokalnym, w razie potrzeby transliterowane na skrypt czytelny 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 z pierwszego komponentu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API użyje najbliższego dopasowania.
    • Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność ich zwracania. Geokoder interpretuje skróty inaczej w zależności od języka, takie jak 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 dwuznakowa wartość kodu CLDR. Nie ma wartości domyślnej. Większość kodów CLDR jest identyczna z kodami ISO 3166-1.

    Podczas geokodowania adresu (geokodowanie wyprzedzające) ten parametr może wpływać na wyniki usługi, ale nie ogranicza ich w pełni do określonego regionu. Podczas geokodowania lokalizacji lub miejsca, odwrotnego geokodowania lub geokodowania miejsca, ten parametr może służyć do formatowania adresu. We wszystkich przypadkach ten parametr może wpływać na wyniki na podstawie obowiązujących przepisów.

  • placeFilter

    Umożliwia filtrowanie wyników wyszukiwania locationQuery pod kątem Twoich wymagań, np. zwracanie tylko miejsc docelowych, które są budynkami, lub tylko miejsc docelowych, które mają wyraźne adresy.

    Filtrowanie według szczegółowości strukturalnej

    Filtr structureType umożliwia określenie rodzaju struktur, które mają być zwracane przez zapytanie:

    • Izolowanie budynków: użyj "structureType": "BUILDING", aby wyświetlić obrysy budynków na mapie lub uzyskać szczegółowe informacje o konkretnej strukturze.
    • Rozumienie kompleksów: użyj "structureType": "GROUNDS", aby głównym wynikiem był cały teren. Jest to przydatne podczas wysyłania zapytań o większe obszary, takie jak kampusy uniwersyteckie lub centra handlowe.
    • Skupianie się na jednostkach/sekcjach: użyj "structureType": "SECTION", aby zidentyfikować sekcje w budynku.

    Zapewnianie przydatnych adresów

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

    • Wymagaj wyraźnego adresu głównego: aby główny wynik miejsca docelowego zawsze zawierał adres lub nazwę na poziomie ulicy, użyj "addressability": "PRIMARY". Jest to przydatne do nawigacji lub wyświetlania, gdy wyraźny adres jest niezbędny.
    • Zezwalaj na adresy w miejscach docelowych: w przypadkach, gdy główne miejsce może nie mieć adresu, ale jednostki w nim (np. apartamenty w budynku) mają adres, "addressability": "WEAK" zapewnia, że co najmniej główne miejsce lub jedno z jego miejsc docelowych 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 obrysy budynków i punkty nawigacyjne, ponieważ poprawia to 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