Поиск направлений

Разработчики из Европейской экономической зоны (ЕЭЗ)

Destination — это важная точка интереса или конкретное место, куда пользователь намеревается добраться или куда хочет направиться. Пункт Destination может включать в себя такую ​​информацию, как точки навигации, ориентиры, входы и очертания зданий.

Конечная точка SearchDestinations API геокодирования позволяет получать подробную информацию о различных пунктах назначения на основе различных входных критериев, таких как адрес, идентификатор места или координаты широты и долготы.

Запрос на поиск направлений

Запрос на поиск целевых адресов представляет собой HTTP POST-запрос к URL-адресу в следующем формате:

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

Передайте все параметры в теле JSON-запроса или в заголовках POST-запроса. Например:

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

Вы можете указать местоположение для поиска пункта назначения одним из трех способов:

  • Адрес
  • Идентификатор места
  • Координаты широты и долготы

Найдите пункт назначения по адресу.

Адрес можно указать в виде неструктурированной строки:

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

или в качестве 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/v4alpha/geocode/destinations

Формат postalAddress обычно используется при обработке адресных компонентов, введенных в HTML-форму.

Найдите пункт назначения по идентификатору места.

Вы можете получить доступ к месту назначения, указав его идентификатор :

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

Найдите пункт назначения по местоположению.

Для поиска пункта назначения укажите координаты широты и долготы:

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

Используйте OAuth для отправки запроса.

API геокодирования версии 4 поддерживает аутентификацию OAuth 2.0 . Для использования OAuth с API геокодирования необходимо присвоить токену OAuth правильную область действия (scope). API геокодирования поддерживает следующие области действия для использования с конечной точкой Destinations:

  • https://www.googleapis.com/auth/maps-platform.geocode — Использовать со всеми конечными точками API геокодирования.

Кроме того, вы можете использовать общую область действия https://www.googleapis.com/auth/cloud-platform для всех конечных точек API геокодирования. Эта область действия полезна на этапе разработки, но не в продакшене, поскольку это общая область, предоставляющая доступ ко всем конечным точкам.

Для получения дополнительной информации и примеров см. раздел «Использование OAuth» .

Ответы на запросы о направлениях поиска

Локальный контекст, касающийся местоположения.

В ответе на запрос «Поиск мест назначения» предоставляется подробная, локальная информация о местоположении. Ключевые поля включают:

  • primary : Основное место, указанное в запросе.
  • containingPlaces : Более крупные объекты, частью которых является основное место назначения (например, торговый центр, в котором находится магазин).
  • subDestinations : Более конкретные места в пределах основного пункта назначения (например, квартиры в здании).
  • entrances : Конкретные точки входа и выхода из пункта назначения.
  • navigationPoints : Подходящие места рядом с дорогой для завершения навигации.
  • arrivalSummary : Аналитические данные, полученные с помощью ИИ, для помощи при прибытии. См. сводные данные, полученные с помощью ИИ .
  • landmarks : Примечательные места поблизости, которые помогут пользователям сориентироваться в окрестностях места назначения.

Подробную информацию обо всех полях ответа см. в справочнике API .

Формат ответа

Функция SearchDestinations возвращает объект SearchDestinationsResponse в следующем формате 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",
          "american_restaurant",
          "meal_takeaway",
          "restaurant",
          "food_store",
          "food",
          "point_of_interest",
          "store",
          "establishment"
        ],
        "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA",
        "postalAddress": {
          "regionCode": "US",
          "languageCode": "en",
          "postalCode": "94087",
          "administrativeArea": "CA",
          "locality": "Sunnyvale",
          "addressLines": [
            "601 S Bernardo Ave"
          ]
        },
        "structureType": "BUILDING",
        "location": {
          "latitude": 37.3734545,
          "longitude": -122.05693269999998
        },
        "displayPolygon":
 { ... } {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.056930138027,
                37.3735253692531
              ],
              [
                -122.056960139391,
                37.3735372663597
              ],
              [
                -122.056994129366,
                37.3734828786847
              ],
              [
                -122.056969677395,
                37.3734731161089
              ],
              [
                -122.057061762447,
                37.3733261309656
              ],
              [
                -122.056979388817,
                37.3732935577128
              ],
              [
                -122.056798860285,
                37.3735818838642
              ],
              [
                -122.056875858081,
                37.3736121235316
              ],
              [
                -122.056930138027,
                37.3735253692531
              ]
            ]
          ]
        }

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

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

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

Необходимые параметры

  • В API-запросе должен присутствовать один из следующих трех параметров, указывающий адрес, место или местоположение, для которого необходимо выполнить поиск:
    • addressQuery - адрес для поиска.
    • place - идентификатор места, которое нужно найти.
    • locationQuery - координаты широты и долготы местоположения, которое необходимо найти.

  • FieldMask

    Укажите список полей, которые должны быть возвращены в ответе, создав маску полей ответа . Передайте маску полей ответа методу, используя параметр URL $fields или fields , или используя заголовок HTTP X-Goog-FieldMask . Например, приведенный ниже запрос вернет только входы, точки навигации и идентификатор места основного пункта назначения.

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

    В ответе отсутствует список возвращаемых полей по умолчанию. Если вы опустите маску поля, метод вернет ошибку. Установите маску поля на * , чтобы вернуть все поля. Дополнительные сведения см. в разделе «Выбор возвращаемых полей» .

Дополнительные параметры

  • travelModes

    Указывает, какие типы navigationPoints следует возвращать. Навигационные точки для других режимов передвижения будут отфильтрованы. Если travelModes не задан, могут быть возвращены навигационные точки для всех режимов передвижения.

  • languageCode

    Язык, на котором будут возвращаться результаты.

    • См. список поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
    • Если languageCode не указан, API по умолчанию использует en . Если вы укажете недопустимый код языка, API вернет ошибку INVALID_ARGUMENT .
    • API делает все возможное, чтобы предоставить уличный адрес, понятный как пользователю, так и местным жителям. Для достижения этой цели он возвращает уличные адреса на местном языке, при необходимости транслитерированные в письменность, понятную пользователю, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочтительном языке. Все компоненты адреса возвращаются на одном языке, который выбирается из первого компонента.
    • Если имя недоступно на предпочитаемом языке, API использует наиболее близкое совпадение.
    • Предпочитаемый язык оказывает незначительное влияние на набор результатов, которые API выбирает для возврата, и на порядок их возврата. Геокодер по-разному интерпретирует сокращения в зависимости от языка, например, сокращения для типов улиц или синонимы, которые могут быть допустимы в одном языке, но не в другом.

  • regionCode

    Региональный код представляет собой двухсимвольное значение кода CLDR . Значение по умолчанию отсутствует. Большинство кодов CLDR идентичны кодам ISO 3166-1.

    При геокодировании адреса ( прямое геокодирование ) этот параметр может влиять на результаты работы сервиса, но не ограничивать их полностью указанным регионом. При геокодировании местоположения ( обратное геокодирование или геокодирование места ) этот параметр может использоваться для форматирования адреса. Во всех случаях этот параметр может влиять на результаты в соответствии с действующим законодательством.

  • placeFilter

    Позволяет фильтровать результаты поиска locationQuery в соответствии с вашими требованиями, например, возвращать только объекты, являющиеся зданиями, или только объекты, имеющие четкие адреса.

    Фильтрация по структурной детализации

    Фильтр structureType позволяет указать тип структур, возвращаемых запросом:

    • Изолирование зданий : используйте "structureType": "BUILDING" , чтобы отобразить контуры зданий на карте или получить подробную информацию о конкретном сооружении.
    • Понимание комплексов : используйте "structureType": "GROUNDS" , чтобы гарантировать, что основным результатом будет вся территория комплекса. Это полезно при запросах к большим территориям, таким как университетские кампусы или торговые центры.
    • При работе с отдельными элементами/секциями : используйте "structureType": "SECTION" , чтобы определить секции внутри здания.

    Убедитесь в наличии полезных адресов.

    Не все населенные пункты имеют четкие адреса на уровне улицы. Фильтр addressability помогает контролировать качество адресов в результатах поиска:

    • Требуется четкий основной адрес : Чтобы гарантировать, что основной результат поиска всегда будет иметь адрес или название улицы, используйте "addressability": "PRIMARY" . Это полезно для навигации или отображения информации, где четкий адрес имеет решающее значение.
    • Разрешить адреса в дополнительных пунктах назначения : В случаях, когда основное место может не иметь адреса, но находящиеся внутри него объекты имеют адрес (например, квартиры в здании), "addressability": "WEAK" гарантирует, что по крайней мере основное место или один из его дополнительных пунктов назначения имеет адрес.
    • Любой результат : Если наличие адреса не имеет значения для вашего варианта использования, используйте "addressability": "ANY" .
    Пример: Фильтрация зданий, имеющих адресную структуру. 
    curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "PRIMARY"
    }
  },
  "languageCode": "en"
}' \\
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\
-H "X-Goog-FieldMask: place" \\
https://geocode.googleapis.com/v4alpha/geocode/destinations

Обратная связь

Это экспериментальная конечная точка API геокодирования. Будем благодарны за отзывы, отправленные по адресу geocoding-feedback-channel@google.com .