Migrar a API Localizar um Local por Endereço do Bing Mapas

2024-05-29

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

Pré-requisitos

Uma conta do Azure
Uma Conta do Azure Mapas
Uma chave de assinatura ou outra forma de autenticação no Azure Mapas

Diferenças notáveis

A API Localizar um Local por Endereço do Bing Mapas só oferece suporte à entrada de geocodificação em formato estruturado, enquanto a API Obter Geocodificação do Azure Mapas oferece suporte à entrada de geocodificação em um formato não estruturado (query=) ou estruturado (addressLine=). Para nomes de referência de geocodificação, use a API Obter geocodificação do Azure Mapas usando o formato de entrada não estruturado.
A API Localizar um Local por Endereço do Bing Mapas retorna coordenadas no formato latitude/longitude, enquanto a API Obter Geocodificação do Azure Mapas retorna coordenadas no formato longitude/latitude, conforme definido pelo formato GeoJSON.
A API Localizar um Local por Endereço do Bing Mapas é compatível com os formatos de resposta XML e JSON. A API Obter geocodificação do Azure Mapas oferece suporte a GeoJSON.
Ao contrário da API Localizar um Local por Endereço do Bing Mapas, a API Obter geocodificação do Azure Mapas tem um parâmetro de entrada view, que é uma cadeia de caracteres que representa um código de região/país ISO 3166-1 Alfa-2. O parâmetro de entrada view altera bordas e rótulos geopolíticos disputados para se 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 um Local por Endereço do Bing Mapas, a API Obter geocodificação do Azure Mapas não oferece suporte à geocodificação de endereços para China, Japão ou Coreia do Sul.
Ao contrário do Bing Mapas para Empresas, o Azure Mapas é um serviço global que suporta a especificação de um escopo geográfico, permitindo que você limite a residência de dados às áreas geográficas (geos) da Europa (UE) ou de América do Norte (EUA). Todas as solicitações (incluindo dados de entrada) são processadas exclusivamente na área geográfica especificada. Para saber mais, confira Escopo geográfico.

Segurança e autenticação

O Bing Mapas para Empresas dá suporte somente à autenticação de chave de API. O Azure Mapas dá suporte a várias opções de autenticação de chamadas de API, como chave de assinatura, Microsoft Entra ID e token de SAS (assinatura de acesso compartilhado). Para obter mais informações sobre segurança e autenticação no Azure Mapas, consulte Autenticação com o Azure Mapas e a seção Segurança na documentação Obter Geocodificação do Azure Mapas.

Parâmetros da solicitação

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

Parâmetro de solicitação do Bing Mapas	Alias do parâmetro de solicitação do Bing Mapas	Parâmetro de solicitação do Azure Mapas	Obrigatório no Azure Mapas	Tipo de dados do Azure Mapas	Descrição
Parâmetro de solicitação do Bing Mapas	Alias do parâmetro de solicitação do Bing Mapas	Parâmetro de solicitação do Azure Mapas	Obrigatório no Azure Mapas	Tipo de dados do Azure Mapas	Observação
addressLine		addressLine	Falso	string	No Azure Mapas, obtenha a API de Geocodificação, um endereço de rua ou endereço de rua com localidade e `adminDistrict`, há suporte para entrada para `addressLine`.
adminDistrict		adminDistrict	Falso	string
countryRegion		countryRegion	Falso	string
localidade		localidade	Falso	string
postalCode		postalCode	Falso	string
culture	c	Cabeçalho da solicitação: Accept-Language	Falso	string	Conforme especificado no cabeçalho da solicitação do Azure Mapas, `culture` define o idioma usado nos resultados da pesquisa quando você usa a API Obter geocodificação do Azure Mapas. Para obter mais informações, confira Linguagens com suporte.
Incluem	Incl	Não é necessário	Não é necessário	Não é necessário	Na API Localizar um Local por Endereço do Bing Mapas, o parâmetro de entrada "include" é necessário para que você obtenha um código de país ISO de duas letras para o resultado do local na resposta (include=ciso2). Na API Obter geocodificação do Azure Mapas, o código de país ISO de duas letras é retornado por padrão.
includeNeighborhood	inclnb	Não é necessário	Não é necessário	Não é necessário	Na API Obter geocodificação do Azure Mapas, as informações de vizinhança são retornadas na resposta por padrão, quando disponíveis.
maxResults	maxRes	top	Falso	Inteiro (int32)	Na API Get Geocoding do Azure Mapas, o número padrão de respostas retornadas é 5. O mínimo é 1 e o máximo é 20.
strictMatch	sm	Sem suporte	Sem suporte	Sem suporte
userIp	Uip	Sem suporte	Sem suporte	Sem suporte
userLocation	ul	coordenadas	Falso	number[]	Na API Obter geocodificação do Azure Mapas, as coordenadas na Terra são especificadas 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	number[]	Uma área retangular na Terra definida como um objeto de caixa delimitadora. Os lados dos retângulos são definidos por valores de longitude e latitude (`longitude1,latitude1,longitude2,latitude2`). Use a seguinte sintaxe 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	ur	exibiçã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 geopolíticos disputados para se alinhar com a região de usuário especificada. Por padrão, o parâmetro View é definido como Automático mesmo se não estiver definido na solicitação. Para saber mais sobre as exibições disponíveis, confira Exibições com suporte.

Para saber mais sobre os parâmetros de solicitação da API Get Geocoding do Azure Mapas, confira Parâmetros de URI.

Exemplos de solicitação

Solicitação POST da API Localizar um Local por Endereço do Bing Mapas:

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

Solicitação POST da API Obter geocodificação do Azure Mapas:

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 quando você executa a solicitação Localizar um Local por Endereço do Bing Mapas e o equivalente no Azure Mapas:

Campo Mapas do Bing	Campo do Azure Mapas	Descrição
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)	address: adminDistricts
endereço: countryRegion (JSON) Endereço: CountryRegion (XML)	endereço: countryRegion
endereço: countryRegionIso2 (JSON) Endereço: CountryRegionIso2 (XML)	endereço: countryRegion - iso
endereço: neighborhood (JSON) Endereço: Neighborhood (XML)	endereço: neighborhood
endereço: formattedAddress (JSON) Endereço: FormattedAddress (XML)	endereço: formattedAddress
endereço: localidade (JSON) Endereço: Locality (XML)	endereço: locality
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)	recursos: bbox	Na API Localizar um Local por Endereço do Bing Mapas, as coordenadas na resposta estão no formato latitude/longitude. As coordenadas na resposta da API Obter geocodificação do Azure Mapas estão no formato longitude/latitude (já que o formato GeoJSON é usado).
calculationMethod (JSON) CalculationMethod (XML)	propriedades: geocodePoints - calculationMethod
confidence (JSON) Confidence (XML)	propriedades: confidence
entityType (JSON) EntityType (XML)	propriedades: type
geocodePoints (JSON) GeocodePoint (XML)	propriedades: geocodePoints - coordinates
matchCodes (JSON) MatchCode (XML)	propriedades: matchCodes
nome (JSON) Nome (XML)	Sem suporte	`formattedAddress` é o equivalente do Azure Mapas.
ponto (JSON) Ponto (XML)	recursos: coordenadas	Na API Localizar um Local por Endereço do Bing Mapas, as coordenadas na resposta estão no formato latitude/longitude. As coordenadas na resposta da API Obter geocodificação do Azure Mapas estão no formato longitude/latitude (já que o formato GeoJSON é usado).
queryParse (JSON) QueryParse (XML)	Sem suporte
usageTypes (JSON) usageType (XML)	propriedades: geocodePoints: usageTypes

Para saber mais sobre os campos de resposta da API Get Geocoding do Azure Mapas, confira Definições.

Exemplos de respostas

A amostra JSON a seguir mostra o que é retornado no corpo da resposta HTTP quando você executa a solicitação do Bing Mapas para Localizar um Local por Endereço:

{ 
    "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"

A amostra JSON a seguir mostra o que é retornado no corpo da resposta HTTP quando você executa uma solicitação Obter geocodificação do Azure Mapas:

{
    "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"
                        }
                    ]
                }
            }
        }
    ]
}

Uso de transações

Assim como a API Localizar um Local por Endereço do Bing Mapas, a API Obter geocodificação do Azure Mapas registra uma transação faturável por solicitação. Para obter mais informações sobre as transações do Azure Mapas, confira Noções básicas sobre transações do Azure Mapas.

Informações adicionais

Get Geocoding Batch: use para enviar um lote de consultas para a API Get Geocoding em uma única solicitação síncrona.

Suporte

Fórum do Microsoft Q&A