Compartilhar via


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

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

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