Перенос API потока данных геокодирования Карт Bing

В этой статье объясняется, как перенести API Geocode Dataflow Bing Maps в API Geocoding Batch и API Reverse Geocoding Batch Azure Maps. API пакетной геокодирования Azure Maps используется для получения координат широты и долготы уличного адреса или названия места в пакетном режиме с помощью одного вызова API. API пакетной службы Azure Maps — это HTTP-запрос POST, который отправляет пакетные пакеты запросов в API геокодирования Azure Maps в одном запросе. API пакетной службы Обратного геокодирования Azure Maps используется для преобразования координат широты и долготы в понятный адрес улицы человека. API пакетного обратного геокодирования Azure Maps — это HTTP-запрос POST, который отправляет пакеты запросов в API обратного геокодирования Azure Maps за один запрос.

Необходимые условия

Заметные различия

  • API потоковой обработки данных Bing Maps поддерживает прямое и обратное пакетное геокодирование в одном API. Azure Maps имеет отдельный API для прямого и обратного геокодирования.
  • API обработки данных для геокодирования Bing Maps требует загрузки ваших данных о расположении в виде XML-файла или текстового файла, разделенного запятыми, вертикальными чертами или табуляцией. Пакетный и обратный геокодинг Azure Maps API не используют подход загрузки файлов данных, а вместо этого используют запрос HTTP POST с данными о местоположении в формате GeoJSON в теле запроса.
  • API Geocode Dataflow Карт Bing поддерживает до 200 000 сущностей за загрузку. Пакетный API геокодирования и обратного геокодирования Azure Maps поддерживает до 100 пакетных запросов при синхронном запросе и до 200 000 при асинхронном запросе.
  • API геокодирования и потоковой передачи данных Bing Maps требует выполнения серии вызовов API после первоначальной загрузки данных, чтобы получить статус и загрузить результаты. Синхронные запросы API пакетного геокодирования и пакетного обратного геокодирования Azure Maps не требуют дополнительных вызовов API. Асинхронный запрос требует дополнительных вызовов для получения состояния пакетного процесса и скачивания результатов.
  • Координаты потока данных Geocode в Bing Maps находятся в формате широты и долготы. Координаты пакетов API геокодирования и обратного геокодирования Azure Maps представлены в формате долготы и широты, поскольку они находятся в формате GeoJSON.
  • В отличие от Bing Maps для предприятий, Azure Maps — это глобальная служба, которая поддерживает указание географического охвата, что позволяет ограничить расположение данных европейскими (ЕС) или американскими (США) географическими областями (геос). Все запросы (включая входные данные) обрабатываются исключительно в указанной географической области. Для получения дополнительной информации см. географическую область охвата службы Azure Maps.

Безопасность и проверка подлинности

Карты Bing для enterprise поддерживают только проверку подлинности ключа API. Azure Maps поддерживает несколько способов проверки подлинности вызовов API, таких как ключ подписки, Microsoft Entra ID или токен общего доступа (SAS). Дополнительные сведения о безопасности и проверке подлинности в Azure Maps см. в разделе "Проверка подлинности с помощью Azure Maps " и раздел "Безопасность " в документации по пакетной службе Azure Maps.

Параметры запроса

В следующей таблице перечислены параметры запроса Dataflow для геокодирования Карт Bing и их эквиваленты в Azure Maps:

Параметр Bing Maps Параметр Azure Maps Описание
dataLocation Не требуется
ввод Не требуется API потока данных Геокодов Bing Maps поддерживает формат XML и текста (csv, tab и разделителя канала) для файла входных данных пакетного геокодирования. Azure Maps поддерживает формат JSON для входных данных пакетного геокодирования в HTTP-запросе POST.
Выход Не требуется API Bing Maps Geocode Dataflow поддерживает JSON и XML для пакетных выходных данных геокодирования. Azure Maps поддерживает формат JSON для выходных данных пакетного геокодирования.

Дополнительные сведения о параметрах URI Azure Maps и тексте запроса см. в документации по пакетной службе Azure Maps и обратному геокодированию пакетной службы .

Сравнение входных и выходных данных схемы карт Bing Maps 2.0 с пакетной службой геокодирования Azure Maps и пакетной службой обратного геокодирования API:

Поле «Bing Maps» Операция Bing Maps Поле Azure Maps Тип данных Azure Maps Описание
Address.AddressLine Запрос геокода
Ответ геокода 		addressLine string
Address.АдминистративныйРайон Запрос геокода
Геокод: Ответ 		административный_округ струна
Address.CountryRegion Запрос геокода
Ответ на запрос геокодирования 		страна/регион струна
Address.District Запрос геокода adminDistrict2 струна
Address.FormattedAddress Ответ геокода
Адрес. Ориентир Ответ геокода Не поддерживается Не поддерживается
Адрес.Локальность Запрос геокода
Ответ геокода 		местность string
Адрес.Район Ответ геокода Район string
Address.PostalCode Запрос геокода
Ответ геокода 		почтовый код string
Адрес.ПочтовыйГород Запрос геокода adminDistrict3
BoundingBox.SouthLatitude, BoundingBox.EastLongitude, BoundingBox.NorthLatitude, BoundingBox.EastLongitude Ответ геокода bbox число[] Используемая проекция для Azure Maps: EPSG:3857. Дополнительные сведения см. в RFC 7946.
Уверенность Ответ геокода Уверенность ConfidenceEnum Дополнительные сведения см. в документации по API пакетного геокодирования и обратного пакетного геокодирования Azure Maps. 
ConfidenceFilter.MinimumConfidence Запрос геокода
Обратный запрос геокода		 Не поддерживается Не поддерживается
Культура Запрос геокода
Обратный запрос геокода		 Заголовок запроса: Accept-Language string Дополнительные сведения см. в статье "Поддерживаемые языки Azure Maps".
Тип сущности Ответ геокода Тип string Дополнительные сведения см. в документации по API пакетного геокодирования и обратного пакетного геокодирования Azure Maps. 
Причина ошибки Ответ геокода Не поддерживается Не поддерживаются
GeocodeEntity КОНТЕЙНЕР XML Не требуется Не требуется
GeocodeFeed КОНТЕЙНЕР XML Не требуется Не требуется
GeocodePoint Ответ геокода geocodePoints GeocodePoints[] Дополнительные сведения см. в документации по API пакетного геокодирования и обратного пакетного геокодирования Azure Maps. 
GeocodeRequest КОНТЕЙНЕР XML Не требуется Не требуется В Azure Maps есть отдельные API для прямого геокодирования и обратного геокодирования.
Id Запрос геокода Не требуется Не требуется
ВключитьТипыСущностей Запрос геокода
Обратный запрос геокода 		Не поддерживается Не поддерживается
Включить соседство Запрос геокода
Обратный запрос геокода 		Не требуется Не требуется В Azure Maps сведения о районе возвращаются в ответе по умолчанию при наличии. 
IncludeQueryParse Запрос геокода Не поддерживается Не поддерживается
Расположение.Широта
Location.МестоположениеДолгота 		Обратный запрос геокода Координаты число[] Требуется в качестве входных данных при использовании API Azure Maps для обратной геокодировки.
MatchCodes Ответ геокода matchCodes MatchCodesEnum Дополнительные сведения см. в документации по API пакетного геокодирования и обратного пакетного геокодирования Azure Maps. 
MaxResults Запрос геокода
Обратный запрос геокода 		Вверх целое число
int32 		Максимальное количество ответов, которые возвращаются в Azure Maps. Значение по умолчанию — 5, минимальное — 1, а максимальное — 20. 
Имя Ответ геокода Не поддерживается Не поддерживается
Point.Широта, Point.Долгота Ответ геокода Координаты число[] Карты Bing возвращают координаты в формате широты и долготы. Azure Maps возвращает координаты в порядке долготы и широты (из-за формата GeoJSON).
Запрос Запрос геокода запрос string
QueryParseValue Ответ геокода Не поддерживается Не поддерживаются
ReverseGeocodeRequest КОНТЕЙНЕР XML Не требуется Не требуется В Azure Maps есть отдельные API для прямого геокодирования и обратного геокодирования.
Код состояния Ответ геокода Не поддерживается Не поддерживается
StrictMatch Запрос геокода Не поддерживается Не поддерживается
TraceId Ответ геокода Не поддерживается Не поддерживается
Версия Не требуется Не требуется

Дополнительная информация о полях ответа пакетного геокодирования Azure Maps доступна в разделе определения.

Примеры запросов

Запрос к API Bing Maps потока данных геокодирования:

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&key={BingMapsKey}

Примеры входных и выходных данных для Geocode Dataflow версии 2.0 можно найти в разделе Geocode Dataflow Sample Input and Output Data Version 2.0.

Запрос API пакетного геокодирования Azure Maps:

POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}

Чтобы отправить запросы геокодирования, используйте HTTP-запрос POST, в котором текст запроса содержит массив batchItems в формате JSON и заголовок Content-Type , заданный для application/json.

В следующем формате JSON показан пример запроса, содержащего два запроса геокодирования, с одним расположением в неструктурированном формате и одним расположением в структурированном формате:

{ 
  "batchItems": [ 
    { 
      "addressLine": "One, Microsoft Way, Redmond, WA 98052", 
      "top": 2 
    }, 
    { 
      "addressLine": "Pike Pl", 
      "adminDistrict": "WA", 
      "locality": "Seattle", 
      "top": 3 
    } 
  ] 
}

Пример запроса API пакетного обратного геокодирования Azure Maps:

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}

Чтобы отправить обратные геокодирующие запросы, используйте HTTP-запрос POST, в котором текст запроса содержит массив batchItems в формате JSON, а заголовок Content-Type имеет значение application/json.

В следующем формате JSON показан пример запроса, содержащего два обратных геокодирующих запроса:

{ 
  "batchItems": [ 
    { 
      "coordinates": [ 
        -122.128275, 
        47.639429 
      ], 
      "resultTypes": [ 
        "Address", 
        "PopulatedPlace" 
      ], 
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B" 
    }, 
    { 
      "coordinates": [ 
        -122.341979399674, 
        47.6095253501216 
      ], 
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7" 
    } 
  ] 
}

Примеры ответов

URL-адрес для скачивания результатов задания геокода предоставляется при успешном выполнении пакетного задания Bing Maps Geocode Dataflow, как показано в состоянии завершенного задания. Пример успешного вывода потока геокодирования данных для карт Bing см. в разделе документации Bing Maps Примеры входных и выходных данных геокода, версия 2.0.

В следующем примере показано, что возвращается в теле HTTP-ответа при выполнении запроса API пакетного геокодирования Azure Maps:

{ 
  "summary": { 
    "successfulRequests": 1, 
    "totalRequests": 2 
  }, 
  "batchItems": [ 
    {
      "type": "FeatureCollection", 
      "features": [ 
        { 
          "type": "Feature", 
          "properties": { 
            "type": "Address", 
            "confidence": "High", 
            "matchCodes": [ 
              "Good" 
            ], 
            "address": { 
              "locality": "Redmond", 
              "adminDistricts": [ 
                { 
                  "shortName": "WA" 
                }, 
                { 
                  "shortName": "King" 
                } 
              ], 
              "countryRegion": { 
                "ISO": "US", 
                "name": "United States" 
              }, 
              "postalCode": "98052", 
              "formattedAddress": "1 Microsoft Way, Redmond, WA 98052", 
              "addressLine": "1 Microsoft Way" 
            }, 
            "geocodePoints": [ 
              { 
                "geometry": { 
                  "type": "Point", 
                  "coordinates": [ 
                    -122.128275, 
                    47.639429 
                  ] 
                }, 
                "calculationMethod": "Rooftop", 
                "usageTypes": [ 
                  "Display", 
                  "Route" 
                ] 
              }, 
              { 
                "geometry": { 
                  "type": "Point", 
                  "coordinates": [ 
                    -122.127028, 
                    47.638545 
                  ] 
                }, 
                "calculationMethod": "Rooftop", 
                "usageTypes": [ 
                  "Route" 
                ] 
              } 
            ] 
          }, 
          "geometry": { 
            "type": "Point", 
            "coordinates": [ 
              -122.128275, 
              47.639429 
            ] 
          }, 
          "bbox": [ 
            -122.1359181505759, 
            47.63556628242932, 
            -122.1206318494241, 
            47.643291717570676 
          ] 
        } 
      ]
    },
    {
      "error": {
        "code": "Conflicting Parameters",
        "message": "When 'query' is present, only the following parameters are valid: 'bbox, location, view, top'. 'addressLine' was passed"
      }
    }
  ]
}

В следующем примере показано, что возвращается в теле HTTP-ответа при выполнении запроса API Azure Maps для массового обратного геокодирования.

{ 
    "batchItems": [ 
        { 
            "type": "FeatureCollection", 
            "features": [ 
                { 
                    "type": "Feature", 
                    "geometry": { 
                        "type": "Point", 
                        "coordinates": [ 
                            -122.1294081, 
                            47.6391325 
                        ] 
                    }, 
                    "properties": { 
                        "geocodePoints": [ 
                            { 
                                "geometry": { 
                                    "type": "Point", 
                                    "coordinates": [ 
                                        -122.1294081, 
                                        47.6391325 
                                    ] 
                                }, 
                                "calculationMethod": "Rooftop", 
                                "usageTypes": [ 
                                    "Display" 
                                ] 
                            } 
                        ], 
                        "address": { 
                            "addressLine": "15770 NE 31st St", 
                            "adminDistricts": [ 
                                { 
                                    "shortName": "WA" 
                                }, 
                                { 
                                    "shortName": "King Co." 
                                } 
                            ], 
                            "countryRegion": { 
                                "name": "United States", 
                                "iso": "US" 
                            }, 
                            "locality": "Redmond", 
                            "neighborhood": "Overlake", 
                            "postalCode": "98052", 
                            "formattedAddress": "15770 NE 31st St, Redmond, WA 98052, United States" 
                        }, 
                        "confidence": "High", 
                        "matchCodes": [ 
                            "Good" 
                        ], 
                        "type": "Address" 
                    }, 
                    "bbox": [ 
                        -122.13705120720665, 
                        47.635269782429326, 
                        -122.12176499279336, 
                        47.64299521757068 
                    ] 
                } 
            ] 
        }, 
        { 
            "type": "FeatureCollection", 
            "features": [ 
                { 
                    "type": "Feature", 
                    "geometry": { 
                        "type": "Point", 
                        "coordinates": [ 
                            -122.341979399674, 
                            47.6095253501216 
                        ] 
                    }, 
                    "properties": { 
                        "geocodePoints": [ 
                            { 
                                "geometry": { 
                                    "type": "Point", 
                                    "coordinates": [ 
                                        -122.341979399674, 
                                        47.6095253501216 
                                    ] 
                                }, 
                                "calculationMethod": "Interpolation", 
                                "usageTypes": [ 
                                    "Display", 
                                    "Route" 
                                ] 
                            } 
                        ], 
                        "address": { 
                            "addressLine": "1736 Pike Pl", 
                            "adminDistricts": [ 
                                { 
                                    "shortName": "WA"
                                }, 
                                { 
                                    "shortName": "King Co." 
                                } 
                            ], 
                            "countryRegion": { 
                                "name": "United States", 
                                "iso": "US" 
                            }, 
                            "intersection": { 
                                "baseStreet": "Pike Pl", 
                                "displayName": "Pike Pl and Stewart St", 
                                "intersectionType": "Near", 
                                "secondaryStreet1": "Stewart St", 
                                "secondaryStreet2": null 
                            }, 
                            "locality": "Seattle", 
                            "neighborhood": "Downtown Seattle", 
                            "postalCode": "98101", 
                            "formattedAddress": "1736 Pike Pl, Seattle, WA 98101, United States" 
                        }, 
                        "confidence": "Medium", 
                        "matchCodes": [ 
                            "Good" 
                        ], 
                        "type": "Address" 
                    }, 
                    "bbox": [ 
                        -122.34961817972945, 
                        47.605662632550924, 
                        -122.33434061961856, 
                        47.61338806769228 
                    ] 
                } 
            ] 
        } 
    ], 
    "summary": { 
        "successfulRequests": 2, 
        "totalRequests": 2 
    } 
}

Использование транзакций

Подобно API обработки геокодов Bing Maps, API пакетного геокодирования Azure Maps и API пакетного обратного геокодирования регистрируют одну оплачиваемую транзакцию для каждого геокодированного элемента. Например, 100 местоположений, геокодированных в пакетном запросе, приводят к 100 оплачиваемым транзакциям. Дополнительные сведения о транзакциях Azure Maps см. в статье "Основные сведения о транзакциях Azure Maps".

Дополнительные сведения

Дополнительные API геокодирования Azure Maps

Поддержка

  • Last updated on