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 w kierunku którego chce się poruszać. 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 danych wejściowych, takich jak adres, identyfikator miejsca lub współrzędne geograficzne.

Żądanie wyszukiwania miejsc docelowych

Żądanie wyszukiwania miejsc docelowych request 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 szerokości i długości geograficznej

Wyszukiwanie miejsca docelowego według adresu

Adres możesz podać jako nieustrukturyzowany ciąg znaków. Geokodowanie adresu nie rozwiązuje współrzędnych geograficznych 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”
Nazwy historyczne, które nie są już używane. „Middlesex United Kingdom”
Elementy lub intencje nieprzestrzenne. „How many boats are in Ventura Harbor?”
Nieoficjalne nazwy lub nazwy własne. „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”), odcinków trasy bez konkretnego numeru lub kodów 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 interfejsu Places API (nowego) z funkcją Search Destinations

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

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

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

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 OAuth 2.0 do uwierzytelniania. 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żywać 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ładów znajdziesz w artykule Używanie OAuth.

Odpowiedź na wyszukiwanie miejsc docelowych

Odpowiedź na wyszukiwanie miejsc docelowych zawiera bogaty, hiperlokalny kontekst dotyczący lokalizacji.

Obiekty PlaceView w odpowiedzi na wyszukiwanie miejsc docelowych (np. primary, elementy w containingPlaces i landmarks) używają pól do wskazywania 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 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.

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 zapewnia dostęp tylko do sklepu z boku budynku, nie będzie to wejście z tagiem "PREFERRED".

structureType

Typ struktury, którą reprezentuje to miejsce.

  • POINT

    Lokalizacja punktowa.

  • SECTION

    Podsekcja budynku.

  • BUILDING

    Budynek.

  • GROUNDS

    Duży obszar, który zwykle obejmuje 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 do lub z 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 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 punkt początkowy do nawigowania do i z miejsca. Punkt jest celowo nieco odsunię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ć następujące:
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

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

arrivalSummary

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

landmarks

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

Format odpowiedzi

SearchDestinations zwraca SearchDestinationsResponse w następującej formie 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 się znajdować 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 szerokości i długości geograficznej 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, używając parametru 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 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 nie podasz parametru languageCode, interfejs API domyślnie użyje wartości en. 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 pocztowy, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby to osiągnąć, zwraca adresy pocztowe 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 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 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 2-znakowa 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 spełnienia Twoich wymagań, np. zwracania 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 mieć pewność, że głównym wynikiem będzie 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 podstawowego: aby mieć pewność, że główny wynik miejsca docelowego zawsze będzie zawierać adres lub nazwę na poziomie ulicy, użyj "addressability": "PRIMARY". Jest to przydatne w przypadku nawigacji lub wyświetlania, gdy wyraźny adres jest kluczowy.
    • Zezwalaj na adresy w miejscach docelowych: w przypadkach, gdy główne miejsce może nie mieć adresu, ale jednostki w nim mają adres (np. apartamenty w budynku), "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".
    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