Ler em inglês

Partilhar via


Migrar o Bing Maps Localizar um local por endereço API

Este artigo explica como migrar a API de Localização por Endereço do Bing Maps para a API de Geocodificação Obter do Azure Maps. A API de Geocodificação Obter Mapas do Azure é usada para obter coordenadas de longitude e latitude de um endereço, um local ou ponto de referência. A API de Obtenção de Geocodificação do Azure Maps dá suporte à entrada de geocodificação em um formato não estruturado ou estruturado. Este artigo aborda cenários em que sua entrada de geocodificação, como endereço, está em formato estruturado - semelhante ao que a API Localizar por Endereço do Bing Maps suporta. Para obter informações sobre como migrar cenários do Bing Maps em que a entrada de geocodificação não está estruturada para obter coordenadas de longitude e latitude de um endereço, local ou ponto de referência, consulte Migrar Bing Maps Localizar um local por API de consulta.

Pré-requisitos

Diferenças notáveis

  • A API Localizar uma Localização por Endereço do Bing Maps suporta apenas a entrada de geocodificação em formato estruturado, enquanto a API Get Geocoding do Azure Maps suporta a entrada de geocodificação num formato não estruturado (query=) ou estruturado (addressLine=). Para nomes de pontos de referência de geocodificação, use a API Get Geocoding do Azure Maps usando o formato de entrada não estruturado.
  • A API Localizar um Local por Endereço do Bing Maps retorna coordenadas no formato latitude/longitude, enquanto a API Obter Geocodificação do Azure Maps retorna coordenadas no formato longitude/latitude, conforme definido pelo formato GeoJSON .
  • A API Localizar um Local por Endereço do Bing Maps suporta o formato de resposta XML e JSON. A API de Geocodificação Obtenha Mapas do Azure suporta GeoJSON.
  • Ao contrário da API de Localização por Endereço do Bing Maps, a API de Geocodificação Obter do Azure Maps tem um view parâmetro de entrada, que é uma cadeia de caracteres que representa um código de região/país ISO 3166-1 Alpha-2. O view parâmetro de entrada altera fronteiras e rótulos geopolíticos disputados para alinhar com a região de usuário especificada. Para obter mais informações, consulte Parâmetros de URI.
  • Ao contrário da API Localizar uma Localização por Endereço do Bing Maps, a API de Geocodificação Obter Mapas do Azure não suporta atualmente a geocodificação de endereços para a China, Japão ou Coreia do Sul.
  • Ao contrário do Bing Maps for Enterprise, o Azure Maps é um serviço global que suporta a especificação de um âmbito geográfico, permitindo limites à residência de dados para as áreas geográficas (geos) europeias (UE) ou dos Estados Unidos (EUA). Todos os pedidos (incluindo dados de cálculo) são processados exclusivamente na área geográfica especificada. Para obter mais informações, consulte Escopo geográfico.

Segurança e autenticação

O Bing Maps for Enterprise suporta apenas a autenticação de chave de API. O Azure Maps dá suporte a várias maneiras de autenticar suas chamadas de API, como uma chave de assinatura, ID do Microsoft Entra e Token de Assinatura de Acesso Compartilhado (SAS). Para obter mais informações sobre segurança e autenticação no Azure Maps, consulte Autenticação com o Azure Maps e a seção Segurança na documentação Obter Geocodificação do Azure Maps.

Parâmetros de solicitação

A tabela a seguir lista os parâmetros de solicitação Localizar um Local por Endereço do Bing Maps e o equivalente do Azure Maps:

Parâmetro de solicitação do Bing Maps Alias de parâmetro de solicitação do Bing Maps Parâmetro de solicitação do Azure Maps Obrigatório no Azure Maps Tipo de dados do Azure Maps Description
Parâmetro de solicitação do Bing Maps Alias de parâmetro de solicitação do Bing Maps Parâmetro de solicitação do Azure Maps Obrigatório no Azure Maps Tipo de dados do Azure Maps Observação
endereçoLinha endereçoLinha Falso string No Azure Maps Obter API de Geocodificação, um endereço ou endereço com localidade e adminDistrict, é suportado para a entrada .addressLine 
adminDistrito adminDistrito Falso string
paísRegião paísRegião Falso string
Localidade Localidade Falso string
Código postal Código postal Falso string
cultura c Cabeçalho da solicitação: Accept-Language Falso string Conforme especificado no cabeçalho da solicitação do Azure Maps, culture define o idioma usado nos resultados da pesquisa ao usar a API Get Geocoding do Azure Maps. Para obter mais informações, consulte Idiomas suportados.
incluem incl Não é necessário Não é necessário Não é necessário Na API Localizar um local por endereço do Bing Maps, o parâmetro de entrada 'include' é necessário para obter um código de país ISO de duas letras para o resultado do local na resposta (include=ciso2). No Azure Maps Get Geocoding API, o código de país ISO de duas letras é retornado por padrão. 
incluirBairro inclnb Não é necessário Não é necessário Não é necessário No Azure Maps Get Geocoding API, as informações de vizinhança são retornadas na resposta por padrão, quando disponíveis. 
maxResultados maxRes Início Falso Inteiro (int32) No Azure Maps Get Geocoding API, o número padrão de respostas retornadas é 5. O mínimo é 1 e o máximo é 20. 
strictMatch SM Não suportado Não suportado Não suportado
userIp UIP Não suportado Não suportado Não suportado
userLocalização ul coordenadas Falso número[] No Azure Maps Obtenha a API de Geocodificação, as coordenadas na Terra especificadas como no formato de longitude e latitude (longitude, latitude). Quando você especifica esse parâmetro, a localização do usuário é considerada e os resultados retornados são mais relevantes para o usuário.
userMapView UMV bbox Falso número[] Uma área retangular na Terra definida como um objeto de caixa delimitadora. Os lados dos retângulos são definidos pelos valores de longitude e latitude (longitude1,latitude1,longitude2,latitude2). Use a sintaxe a seguir para especificar uma caixa delimitadora:

Longitude Oeste, Latitude Sul, Longitude Leste, Latitude Norte

Quando você especifica esse parâmetro, a área geográfica é levada em conta ao calcular os resultados de uma consulta de local.
userRegion o seu Visão Falso string Uma cadeia de caracteres que representa um código de região/país ISO 3166-1 Alpha-2 que altera bordas e rótulos disputados geopoliticamente para alinhar com a região de usuário especificada. Por padrão, o parâmetro View é definido como Auto mesmo se não estiver definido na solicitação. Para obter mais informações sobre modos de exibição disponíveis, consulte Modos de exibição suportados.

Para obter mais informações sobre os parâmetros de solicitação da API Get Geocoding do Azure Maps, consulte Parâmetros de URI.

Exemplos de pedidos

Bing Maps Localizar um local por endereço API POST solicitação:

HTTP
http://dev.virtualearth.net/REST/v1/Locations/US/WA/Redmond/15127 NE 24th Street?&key={BingMapsKey}        

Azure Maps Obter solicitação POST da API de Geocodificação :

HTTP
https://atlas.microsoft.com/geocode?api-version=2023-06-01&adminDistrict=WA&locality=Redmond&addressLine=15127 NE 24th Street&subscription-key={Your-Azure-Maps-Subscription-key}

Campos de resposta

A tabela a seguir lista os campos que podem aparecer na resposta HTTP ao executar a solicitação Localizar um Local por Endereço do Bing Maps e o equivalente do Azure Maps:

Campo Mapas do Bing Campo do Azure Maps Description
endereço: addressLine (JSON)

Endereço: AddressLine (XML)
endereço: addressLine
endereço: adminDistrict (JSON)

Endereço: AdminDistrict (XML)
endereço: adminDistricts
endereço: adminDistrict2 (JSON)

Endereço: AdminDistrict2 (XML)
endereço: adminDistricts
endereço: countryRegion (JSON)

Endereço: CountryRegion (XML)
endereço: paísRegião
endereço: countryRegionIso2 (JSON)

Endereço: CountryRegionIso2 (XML)
endereço: countryRegion - iso
endereço: bairro (JSON)

Endereço: Bairro (XML)
Endereço: Bairro
endereço: formattedAddress (JSON)

Endereço: FormattedAddress (XML)
endereço: formattedAddress
endereço: localidade (JSON)

Endereço: Localidade (XML)
Endereço: Localidade
endereço: postalCode (JSON)

Endereço: PostalCode (XML)
endereço: postalCode
endereço: Intersection – baseStreet (JSON)

Endereço: Intersection – BaseStreet (XML)
endereço: intersection -baseStreet
endereço: Intersection – secondaryStreet1 (JSON)

Endereço: Intersection - SecondaryStreet1
endereço: Intersection – secondaryStreet2 (JSON)

Endereço: Intersection – SecondaryStreet2 (XML)
Endereço: Intersection - SecondaryStreet2
endereço: Intersection – intersectionType (JSON)

Endereço: Intersection – IntersectionType (XML)
endereço: intersection - intersectionType
endereço: Intersection – displayName (JSON)

Endereço: Intersection – DisplayName (XML)
endereço: intersection - displayName
bbox (JSON)

BoundingBox (XML)
Características: BBOX Na API Localizar um Local por Endereço do Bing Maps, as coordenadas na resposta estão no formato latitude/longitude. As coordenadas na resposta da API de Geocodificação Get do Azure Maps estão no formato longitude/latitude (já que o formato GeoJSON é usado).  
Método de cálculo (JSON)

Método de cálculo (XML)
propriedades: geocodePoints - calculationMethod
confiança (JSON)

Confiança (XML)
propriedades: confiança
entityType (JSON)

EntityType (XML)
propriedades: tipo
geocodePoints (JSON)

GeocodePoint (XML)
propriedades: geocodePoints - coordenadas
matchCodes (JSON)

Código de correspondência (XML)
propriedades: matchCodes
nome (JSON)

Nome (XML)
Não suportado formattedAddress é o equivalente do Azure Maps.
ponto (JSON)

Ponto (XML)
características: coordenadas Na API Localizar um Local por Endereço do Bing Maps, as coordenadas na resposta estão no formato latitude/longitude. As coordenadas na resposta da API de Geocodificação Get do Azure Maps estão no formato longitude/latitude (já que o formato GeoJSON é usado).  
queryParse (JSON)

QueryParse (XML)
Não suportado
usageTypes (JSON)

usageType (XML)
propriedades: geocodePoints: usageTypes

Para obter mais informações sobre os campos de resposta da API de Geocodificação do Azure Maps Get, consulte Definições.

Exemplos de respostas

O exemplo JSON a seguir mostra o que é retornado no corpo da resposta HTTP ao executar a solicitação Localizar um local por endereço do Bing Maps:

JSON
{ 
    "authenticationResultCode": "ValidCredentials", 
    "brandLogoUri": "https://dev.virtualearth.net/Branding/logo_powered_by.png", 
    "copyright": "Copyright © 2024 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.", 
    "resourceSets": [ 
        { 
            "estimatedTotal": 1, 
            "resources": [ 
                { 
                    "__type": "Location:http://schemas.microsoft.com/search/local/ws/rest/v1", 
                    "bbox": [ 
                        47.62649628242932, 
                        -122.14631082421619, 
                        47.634221717570675, 
                        -122.1310271757838 
                    ], 
                    "name": "15127 NE 24th St, Redmond, WA 98052", 
                    "point": { 
                        "type": "Point", 
                        "coordinates": [ 
                            47.630359, 
                            -122.138669 
                        ] 
                    }, 
                    "address": { 
                        "addressLine": "15127 NE 24th St", 
                        "adminDistrict": "WA", 
                        "adminDistrict2": "King County", 
                        "countryRegion": "United States", 
                        "formattedAddress": "15127 NE 24th St, Redmond, WA 98052", 
                        "locality": "Redmond", 
                        "postalCode": "98052" 
                    }, 
                    "confidence": "High", 
                    "entityType": "Address", 
                    "geocodePoints": [ 
                        { 
                            "type": "Point", 
                            "coordinates": [ 
                                47.630359, 
                                -122.138669 
                            ], 
                            "calculationMethod": "Rooftop", 
                            "usageTypes": [ 
                                "Display" 
                            ] 
                        }, 
                        { 
                            "type": "Point", 
                            "coordinates": [ 
                                47.630563, 
                                -122.1387383 
                            ], 
                            "calculationMethod": "Rooftop", 
                            "usageTypes": [ 
                                "Route" 
                            ] 
                        } 
                    ], 
                    "matchCodes": [ 
                        "Good" 
                    ] 
                } 
            ] 
        } 
    ], 
    "statusCode": 200, 
    "statusDescription": "OK", 
    "traceId": "e0a7cb31a835ffbcc7e2b8f6b1a0b4e0|MWH0032BE3|0.0.0.1|Ref A: 9BC4F0B708B04F2EA6D52CB3461458A6 Ref B: CO1EDGE1411 Ref C: 2024-04-23T23:44:47Z"

O exemplo JSON a seguir mostra o que é retornado no corpo da resposta HTTP ao executar uma solicitação Get Geocoding do Azure Maps:

JSON
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -122.138679,
                    47.630356
                ]
            },
            "bbox": [
                -122.14632082377759,
                47.62649328242932,
                -122.1310371762224,
                47.634218717570675
            ],
            "properties": {
                "type": "Address",
                "confidence": "High",
                "matchCodes": [
                    "Good"
                ],
                "geocodePoints": [
                    {
                        "calculationMethod": "Rooftop",
                        "usageTypes": [
                            "Display"
                        ],
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                -122.138679,
                                47.630356
                            ]
                        }
                    },
                    {
                        "calculationMethod": "Rooftop",
                        "usageTypes": [
                            "Route"
                        ],
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                -122.138685,
                                47.6305637
                            ]
                        }
                    }
                ],
                "address": {
                    "addressLine": "15127 NE 24th St",
                    "postalCode": "98052",
                    "locality": "Redmond",
                    "formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
                    "countryRegion": {
                        "name": "United States",
                        "ISO": "US"
                    },
                    "adminDistricts": [
                        {
                            "shortName": "WA"
                        },
                        {
                            "shortName": "King County"
                        }
                    ]
                }
            }
        }
    ]
}

Utilização de transações

Como o Bing Maps Localizar um local por endereço API, o Azure Maps Obter API de Geocodificação registra uma transação faturável por solicitação. Para obter mais informações sobre transações do Azure Maps, consulte Noções básicas sobre transações do Azure Maps.

Informações adicionais

Suporte