Search - Get Geocoding Batch
Slouží k odeslání dávky dotazů do rozhraní API pro geokódování v rámci jednoho požadavku.
Rozhraní Get Geocoding Batch
API je požadavek HTTP POST
, který v jednom požadavku odesílá dávky až 100 dotazů do rozhraní API pro geokódování .
Odeslání synchronní dávkové žádosti
Synchronní rozhraní API se doporučuje pro zjednodušené dávkové požadavky. Když služba obdrží požadavek, zareaguje, jakmile se dávkové položky vypočítají, a nebude možné později načíst výsledky. Synchronní rozhraní API vrátí chybu časového limitu (odpověď 408), pokud požadavek trvá déle než 60 sekund. Počet položek dávky je pro toto rozhraní API omezený na 100 .
POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01
Text POST pro žádost Batch
K odeslání geokódovacích dotazů použijete POST
požadavek, kde text požadavku bude obsahovat batchItems
pole ve json
formátu a hlavička Content-Type
bude nastavená na application/json
. Tady je ukázkový text požadavku, který obsahuje 2 geokódovací dotazy:
{
"batchItems": [
{
"addressLine": "One, Microsoft Way, Redmond, WA 98052",
"top": 2
},
{
"addressLine": "Pike Pl",
"adminDistrict": "WA",
"locality": "Seattle",
"top": 3
}
]
}
Objekt batchItem geokódování může přijmout libovolný z podporovaných parametrů identifikátoru URIgeografického kódování.
Dávka by měla obsahovat alespoň 1 dotaz.
Model dávkové odpovědi
Dávková odpověď obsahuje komponentu summary
totalRequests
, která označuje, které byly součástí původního dávkového požadavku, tj successfulRequests
. dotazy, které byly úspěšně provedeny. Dávková odpověď obsahuje batchItems
také pole, které obsahuje odpověď pro každý dotaz v dávkovém požadavku. Bude batchItems
obsahovat výsledky ve stejném pořadí, v jakém byly původní dotazy odeslány v dávkovém požadavku. Každá položka má jeden z následujících typů:
GeocodingResponse
– Pokud se dotaz úspěšně dokončil.Error
– Pokud dotaz selhal. Odpověď bude v tomto případě obsahovat acode
.message
POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01
Parametry identifikátoru URI
Name | V | Vyžadováno | Typ | Description |
---|---|---|---|---|
api-version
|
query | True |
string |
Číslo verze rozhraní API Azure Maps. |
Hlavička požadavku
Name | Vyžadováno | Typ | Description |
---|---|---|---|
x-ms-client-id |
string |
Určuje, který účet je určen pro použití ve spojení s modelem zabezpečení Azure AD. Představuje jedinečné ID účtu Azure Maps a dá se načíst z rozhraní API účtu Azure Maps roviny správy. Pokud chcete použít zabezpečení Azure AD v Azure Maps pokyny najdete v následujících článcích. |
|
Accept-Language |
string |
Jazyk, ve kterém se mají vracet výsledky hledání. Podrobnosti najdete v části Podporované jazyky . |
Text požadavku
Name | Typ | Description |
---|---|---|
batchItems |
Seznam dotazů ke zpracování |
Odpovědi
Name | Typ | Description |
---|---|---|
200 OK |
OK |
|
Other Status Codes |
Došlo k neočekávané chybě. |
Zabezpečení
AADToken
Toto jsou Microsoft Entra toky OAuth 2.0. Při spárování s řízením přístupu na základě role v Azure se dá použít k řízení přístupu k Azure Maps rozhraní REST API. Řízení přístupu na základě role v Azure slouží k určení přístupu k jednomu nebo několika Azure Maps účtu prostředku nebo dílčím prostředkům. Každému uživateli, skupině nebo instančnímu objektu je možné udělit přístup prostřednictvím předdefinované role nebo vlastní role, která se skládá z jednoho nebo více oprávnění k Azure Maps rozhraní REST API.
Pokud chcete implementovat scénáře, doporučujeme zobrazit si koncepty ověřování. Souhrnně řečeno, tato definice zabezpečení poskytuje řešení pro modelování aplikací prostřednictvím objektů schopných řízení přístupu k určitým rozhraním API a oborům.
Poznámka
- Tato definice zabezpečení vyžaduje použití hlavičky
x-ms-client-id
k označení Azure Maps prostředku, ke kterému aplikace žádá o přístup. To je možné získat z rozhraní API pro správu map. - Je
Authorization URL
specifický pro instanci veřejného cloudu Azure. Suverénní cloudy mají jedinečné autorizační adresy URL a konfigurace Microsoft Entra ID. - Řízení přístupu na základě role v Azure se konfiguruje z roviny správy Azure prostřednictvím Azure Portal, PowerShellu, rozhraní příkazového řádku, sad Azure SDK nebo rozhraní REST API.
- Použití sady Azure Maps Web SDK umožňuje nastavit aplikaci na základě konfigurace pro více případů použití.
- Další informace o Microsoft identity platform najdete v přehledu Microsoft identity platform.
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
Name | Description |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
Jedná se o sdílený klíč, který se zřizuje při vytváření Azure Maps prostředku prostřednictvím roviny správy Azure prostřednictvím Azure Portal, PowerShellu, rozhraní příkazového řádku, sad Azure SDK nebo rozhraní REST API.
S tímto klíčem má každá aplikace oprávnění pro přístup ke všem rozhraním REST API. Jinými slovy, ty je v současné době možné považovat za hlavní klíče k účtu, pro který jsou vystaveny.
U veřejně vystavených aplikací doporučujeme používat přístup mezi servery Azure Maps rozhraní REST API, ve kterých lze tento klíč bezpečně uložit.
Type:
apiKey
In:
header
SAS Token
Jedná se o token sdíleného přístupového podpisu, který se vytvoří z operace List SAS v Azure Maps prostředku prostřednictvím roviny správy Azure prostřednictvím Azure Portal, PowerShellu, rozhraní příkazového řádku, sad Azure SDK nebo rozhraní REST API.
S tímto tokenem má každá aplikace autorizaci pro přístup pomocí řízení přístupu na základě role v Azure a podrobnou kontrolu vypršení platnosti, četnosti a oblastí použití konkrétního tokenu. Jinými slovy, token SAS je možné použít k tomu, aby aplikace mohly řídit přístup zabezpečeným způsobem než sdílený klíč.
U veřejně vystavených aplikací doporučujeme nakonfigurovat konkrétní seznam povolených zdrojů v prostředku účtu map , aby se omezilo zneužití vykreslování, a pravidelně obnovovat token SAS.
Type:
apiKey
In:
header
Příklady
A Geocoding Batch API call containing 2 Geocoding queries
Sample Request
POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01
{
"batchItems": [
{
"addressLine": "One, Microsoft Way, Redmond, WA 98052",
"top": 2,
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
},
{
"addressLine": "Pike Pl",
"adminDistrict": "WA",
"locality": "Seattle",
"top": 3
}
]
}
Sample Response
{
"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"
}
}
]
}
Definice
Name | Description |
---|---|
Address |
Adresa výsledku |
Admin |
Název dílčího dělení v zemi nebo oblasti pro adresu. Tento prvek se obvykle považuje za správní pododdíl prvního řádu, ale v některých případech obsahuje také pododdíl druhého, třetího nebo čtvrtého pořadí v zemi, závislosti nebo oblasti. |
Calculation |
Metoda, která se použila k výpočtu bodu geografického kódu. |
Confidence |
Úroveň spolehlivosti, že výsledek geokódovaného umístění odpovídá. Tuto hodnotu použijte spolu s kódem shody k určení úplnějších informací o shodě. Spolehlivost geograficky zakódovaného umístění je založena na mnoha faktorech, včetně relativní důležitosti geograficky zakódovaného umístění a polohy uživatele, pokud je zadána. |
Country |
|
Error |
Další informace o chybě správy prostředků |
Error |
Podrobnosti o chybě. |
Error |
Odpověď na chybu |
Feature |
Typ FeatureCollection objektu musí být FeatureCollection. |
Features |
|
Feature |
Typ funkce musí být Funkce. |
Geocode |
Kolekce bodů geografického kódu, které se liší ve způsobu jejich výpočtu a navrhovaném použití. |
Geocoding |
Seznam dotazů a požadavků na geografické kódování adres ke zpracování. Seznam může obsahovat maximálně 100 dotazů a musí obsahovat alespoň 1 dotaz. |
Geocoding |
Objekt batch query |
Geocoding |
Tento objekt se vrátí z úspěšného volání služby Batch geokódování. |
Geocoding |
|
Geo |
Platný |
Intersection |
Adresa výsledku. |
Match |
Jedna nebo více hodnot kódu shody, které představují úroveň geografického kódování pro každé umístění v odpovědi. Například geograficky zakódované umístění s kódy shody a Podobně geograficky zakódované umístění s kódy shody a Možné hodnoty jsou:
|
Properties | |
Summary |
Shrnutí dávkové žádosti |
Usage |
Nejlepší použití pro bod geografického kódu.
Každý bod geografického |
Address
Adresa výsledku
Name | Typ | Description |
---|---|---|
addressLine |
string |
AddressLine, která obsahuje název ulice a číslo |
adminDistricts |
Název dílčího dělení v zemi nebo oblasti pro adresu. Tento prvek se obvykle považuje za správní pododdíl prvního řádu, ale v některých případech obsahuje také pododdíl druhého, třetího nebo čtvrtého pořadí v zemi, závislosti nebo oblasti. |
|
countryRegion | ||
formattedAddress |
string |
Vlastnost Formátovaná adresa |
intersection |
Adresa výsledku. |
|
locality |
string |
lokalita – vlastnost |
neighborhood |
string |
sousedská vlastnost |
postalCode |
string |
Vlastnost PSČ |
AdminDistricts
Název dílčího dělení v zemi nebo oblasti pro adresu. Tento prvek se obvykle považuje za správní pododdíl prvního řádu, ale v některých případech obsahuje také pododdíl druhého, třetího nebo čtvrtého pořadí v zemi, závislosti nebo oblasti.
Name | Typ | Description |
---|---|---|
name |
string |
Název odpovídajícího pole adminDistrict For adminDistrict[0], může to být úplný název státu, například Washington, For adminDistrict[1], může to být úplný název okresu. |
shortName |
string |
Krátký název odpovídajícího pole adminDistrict For adminDistrict[0], může to být krátký název státu, například WA, Pro adminDistrict[1], může to být krátký název okresu. |
CalculationMethodEnum
Metoda, která se použila k výpočtu bodu geografického kódu.
Name | Typ | Description |
---|---|---|
Interpolation |
string |
Bod geografického kódu byl spárován s bodem na silnici pomocí interpolace. |
InterpolationOffset |
string |
Bod geokódu byl spárován s bodem na silnici pomocí interpolace s dodatečným posunem, aby se bod přesunul na stranu ulice. |
Parcel |
string |
Bod geokódu byl spárován se středem parcely. |
Rooftop |
string |
Bod geokódu byl spárován se střechou budovy. |
ConfidenceEnum
Úroveň spolehlivosti, že výsledek geokódovaného umístění odpovídá. Tuto hodnotu použijte spolu s kódem shody k určení úplnějších informací o shodě.
Spolehlivost geograficky zakódovaného umístění je založena na mnoha faktorech, včetně relativní důležitosti geograficky zakódovaného umístění a polohy uživatele, pokud je zadána.
Name | Typ | Description |
---|---|---|
High |
string |
Pokud je hodnota spolehlivosti nastavená na Pokud žádost obsahuje umístění nebo zobrazení, může se pořadí odpovídajícím způsobem změnit. Například dotaz na umístění pro "Paříž" vrátí "Paříž, Francie" a "Paříž, TX" s |
Low |
string |
|
Medium |
string |
V některých situacích nemusí být vrácená shoda na stejné úrovni jako informace uvedené v požadavku. Požadavek může například zadat informace o adrese a služba geografického kódu může být schopna spárovat pouze psč. V takovém případě, pokud má služba geografického kódu jistotu, že PSČ odpovídá datům, je nastavena na Pokud jsou informace o poloze v dotazu nejednoznačné a neexistují žádné další informace pro pořadí umístění (například umístění uživatele nebo relativní důležitost umístění), je spolehlivost nastavená na Pokud informace o poloze v dotazu neposkytují dostatek informací ke geografickému kódování konkrétního umístění, může být vrácena méně přesná hodnota umístění a spolehlivost je nastavena na |
CountryRegion
Name | Typ | Description |
---|---|---|
ISO |
string |
ISO země/oblasti |
name |
string |
název země/oblasti |
ErrorAdditionalInfo
Další informace o chybě správy prostředků
Name | Typ | Description |
---|---|---|
info |
object |
Další informace. |
type |
string |
Další typ informací. |
ErrorDetail
Podrobnosti o chybě.
Name | Typ | Description |
---|---|---|
additionalInfo |
Další informace o chybě |
|
code |
string |
Kód chyby |
details |
Podrobnosti o chybě |
|
message |
string |
Chybová zpráva |
target |
string |
Cíl chyby. |
ErrorResponse
Odpověď na chybu
Name | Typ | Description |
---|---|---|
error |
Objekt chyby. |
FeatureCollectionEnum
Typ FeatureCollection objektu musí být FeatureCollection.
Name | Typ | Description |
---|---|---|
FeatureCollection |
string |
FeaturesItem
Name | Typ | Description |
---|---|---|
bbox |
number[] |
Ohraničující rámeček. Použitá projekce – EPSG:3857. Podrobnosti najdete v dokumentu RFC 7946 . |
geometry |
Platný |
|
id |
string |
ID vrácené funkce |
properties | ||
type |
Typ funkce musí být Funkce. |
FeatureTypeEnum
Typ funkce musí být Funkce.
Name | Typ | Description |
---|---|---|
Feature |
string |
GeocodePoints
Kolekce bodů geografického kódu, které se liší ve způsobu jejich výpočtu a navrhovaném použití.
Name | Typ | Description |
---|---|---|
calculationMethod |
Metoda, která se použila k výpočtu bodu geografického kódu. |
|
geometry |
Platný |
|
usageTypes |
Nejlepší použití pro bod geografického kódu.
Každý bod geografického |
GeocodingBatchRequestBody
Seznam dotazů a požadavků na geografické kódování adres ke zpracování. Seznam může obsahovat maximálně 100 dotazů a musí obsahovat alespoň 1 dotaz.
Name | Typ | Description |
---|---|---|
batchItems |
Seznam dotazů ke zpracování |
GeocodingBatchRequestItem
Objekt batch query
Name | Typ | Výchozí hodnota | Description |
---|---|---|---|
addressLine |
string |
Oficiální řádek ulice adresy vzhledem k oblasti, jak je specifikováno vlastností lokality nebo PSČ. Typickým použitím tohoto prvku je zadání adresy nebo jakékoli oficiální adresy. Pokud je dotaz zadaný, neměl by tento parametr používat. |
|
adminDistrict |
string |
Část adresy subdivision country, například WA. Pokud je dotaz zadaný, neměl by tento parametr používat. |
|
adminDistrict2 |
string |
Hrabství pro strukturovanou adresu, například King. Pokud je dotaz zadaný, neměl by tento parametr používat. |
|
adminDistrict3 |
string |
Pojmenovaná oblast strukturované adresy Pokud je dotaz zadaný, neměl by tento parametr používat. |
|
bbox |
number[] |
Obdélníková oblast na zemi definovaná jako objekt ohraničujícího rámečku. Strany obdélníků jsou definovány hodnotami zeměpisné délky a zeměpisné šířky. Další informace najdete v tématu Typy umístění a oblasti. Při zadání tohoto parametru se při výpočtu výsledků dotazu na umístění bere v úvahu geografická oblast. Příklad: [lon1, lat1, lon2, lat2] |
|
coordinates |
number[] |
Bod na Zemi zadaný jako zeměpisná délka a zeměpisná šířka. Při zadání tohoto parametru se bere v úvahu umístění uživatele a vrácené výsledky můžou být pro uživatele relevantnější. Příklad: [lon, lat] |
|
countryRegion |
string |
Signál pro výsledek geokódování pro iso 3166-1 Alfa-2 kód oblasti/země , který je zadán, např. FR./ Pokud je dotaz zadaný, neměl by tento parametr používat. |
|
locality |
string |
Místní část adresy, například Seattle. Pokud je dotaz zadaný, neměl by tento parametr používat. |
|
optionalId |
string |
id požadavku, které by se zobrazilo v odpovídající dávce |
|
postalCode |
string |
Část poštovního směrovacího čísla adresy. Pokud je dotaz zadaný, neměl by tento parametr používat. |
|
query |
string |
Řetězec, který obsahuje informace o umístění, například adresu nebo název orientačního bodu. |
|
top |
integer |
5 |
Maximální počet odpovědí, které budou vráceny. Výchozí hodnota: 5, minimum: 1 a maximum: 20. |
view |
string |
auto |
Řetězec, který určuje kód oblasti/země ISO 3166-1 Alpha-2. Tím se změní geopolitické sporné ohraničení a popisky tak, aby odpovídaly zadané oblasti uživatele. |
GeocodingBatchResponse
Tento objekt se vrátí z úspěšného volání služby Batch geokódování.
Name | Typ | Description |
---|---|---|
batchItems |
Pole obsahující výsledky dávky. |
|
nextLink |
string |
Je odkaz na další stránku vrácených funkcí. Pokud je to poslední stránka, toto pole není. |
summary |
Shrnutí dávkové žádosti |
GeocodingBatchResponseItem
Name | Typ | Description |
---|---|---|
error |
Podrobnosti o chybě. |
|
features | ||
nextLink |
string |
Je odkaz na další stránku vrácených funkcí. Pokud je to poslední stránka, toto pole není. |
optionalId |
string |
id batchItem, které by bylo stejné jako ID v požadavku. |
type |
Typ FeatureCollection objektu musí být FeatureCollection. |
GeoJsonPoint
Platný GeoJSON Point
typ geometrie. Podrobnosti najdete v dokumentu RFC 7946 .
Name | Typ | Description |
---|---|---|
bbox |
number[] |
Ohraničující rámeček. Použitá projekce – EPSG:3857. Podrobnosti najdete v dokumentu RFC 7946 . |
coordinates |
number[] |
A |
type |
string:
Point |
Určuje |
Intersection
Adresa výsledku.
Name | Typ | Description |
---|---|---|
baseStreet |
string |
Primární ulice pro umístění. |
displayName |
string |
Úplný název průsečíku |
intersectionType |
string |
Typ průsečíku. |
secondaryStreet1 |
string |
První protínající se ulice. |
secondaryStreet2 |
string |
Pokud existuje, druhá protínající se ulice. |
MatchCodesEnum
Jedna nebo více hodnot kódu shody, které představují úroveň geografického kódování pro každé umístění v odpovědi.
Například geograficky zakódované umístění s kódy shody a Ambiguous
znamená, že pro informace o poloze bylo nalezeno více než jedno umístění geografického Good
kódu a že služba geografického kódu neměla vyhledávání v hierarchii, aby našla shodu.
Podobně geograficky zakódované umístění s kódy shody a UpHierarchy
naznačuje, že nelze najít umístění geografického Ambiguous
kódu, které by odpovídalo všem zadaným informacím o poloze, takže služba geografického kódu musela prohledávat hierarchii a na této úrovni našla více shod. Příkladem výsledku Ambiguous
a UpHierarchy
je, že zadáte úplné informace o adrese, ale služba geografického kódu nemůže najít shodu pro adresu ulice a místo toho vrátí informace pro více než jednu hodnotu RoadBlock.
Možné hodnoty jsou:
Good
: Umístění má pouze jednu shodu nebo všechny vrácené shody jsou považovány za silné shody. Například dotaz pro New York vrátí několik dobrých shod.
Ambiguous
: Umístění je jednou ze sady možných shod. Například při dotazu na adresu ulice 128 Main St. může odpověď vrátit dvě umístění pro 128 North Main St. a 128 South Main St., protože není k dispozici dostatek informací k určení, kterou možnost zvolit.
UpHierarchy
: Umístění představuje přesun v geografické hierarchii nahoru. K tomu dochází v případě, že nebyla nalezena shoda pro žádost o umístění, takže se vrátí méně přesný výsledek. Pokud například nelze najít shodu pro požadovanou adresu, může být vrácen kód UpHierarchy
shody s typem entity RoadBlock.
Name | Typ | Description |
---|---|---|
Ambiguous |
string |
|
Good |
string |
|
UpHierarchy |
string |
Properties
Name | Typ | Description |
---|---|---|
address |
Adresa výsledku |
|
confidence |
Úroveň spolehlivosti, že výsledek geokódovaného umístění odpovídá. Tuto hodnotu použijte spolu s kódem shody k určení úplnějších informací o shodě. Spolehlivost geograficky zakódovaného umístění je založena na mnoha faktorech, včetně relativní důležitosti geograficky zakódovaného umístění a polohy uživatele, pokud je zadána. |
|
geocodePoints |
Kolekce bodů geografického kódu, které se liší ve způsobu jejich výpočtu a navrhovaném použití. |
|
matchCodes |
Jedna nebo více hodnot kódu shody, které představují úroveň geografického kódování pro každé umístění v odpovědi. Například geograficky zakódované umístění s kódy shody a Podobně geograficky zakódované umístění s kódy shody a Možné hodnoty jsou:
|
|
type |
string |
Jedna z těchto možností:
|
Summary
Shrnutí dávkové žádosti
Name | Typ | Description |
---|---|---|
successfulRequests |
integer |
Počet úspěšných požadavků v dávce |
totalRequests |
integer |
Celkový počet požadavků v dávce |
UsageTypeEnum
Nejlepší použití pro bod geografického kódu.
Každý bod geografického Route
kódu je definován jako bod, Display
bod nebo obojí.
Pokud vytváříte trasu do umístění, použijte Route
body. Pokud zobrazujete polohu na mapě, použijte Display
body. Pokud je například místem park, může bod určit vstup do parku, Route
kam můžete vstoupit autem, a Display
bod může být bod, který určuje střed parku.
Name | Typ | Description |
---|---|---|
Display |
string |
|
Route |
string |