The geocoder response
The geocoder API response is available in the following formats: XML, JSON, and JSONP. The necessary response format is set in the format parameter of the request. Information returned in the response does not depend on the selected format.
Response content
- Key elements
-
- The GeocoderResponseMetaData element contains information about the request and the number of results found.
- The GeocoderMetaData element contains the text of the request, the type of the object found, the precision of matching the result to the request, and the object's address.
- The Point element contains the coordinates of the center of the object.
- The boundedBy element contains the boundaries of the viewport within which it is recommended to show the object on the map. For most objects, the viewport is a rectangle around the object.
- Order of results
-
- For direct geocoding (the coordinates are determined using the address and/or name), the results are sorted according to their similarity to the address or name specified in the request.
- For reverse geocoding (the address is determined from the coordinates), the results are sorted according to the size of the geometric area that the object belongs to, in reverse order (house number, street, district, city, and so on).
- Order of coordinates
-
The geocoder response returns the coordinates in the sequence “longitude latitude”. This order does not depend on the coordinate format in the request.
- Namespaces
-
- The root element is located in the ymaps namespace.
- Metadata elements (GeocoderResponseMetaData and GeocoderMetaData) and all their nested elements, except AddressDetails, are located in the designated geocoder namespace
yg. - The address is in the Address element included in the
anamespace. - The response also uses standard GML elements.
For more information about namespaces, see Namespaces used.
The response in XML format
By default, the geocoder response is returned in XML format. Below is a response to a request with the Sultanahmet Camii in Istanbul address:
https://geocode-maps.yandex.ru/1.x/?apikey=<Ваш API-ключ>&geocode=Sultanahmet+Camii+İç+Yolları&lang=en-USResponse:
<?xml version="1.0" encoding="utf-8"?>
<ymaps xmlns="http://maps.yandex.ru/ymaps/1.x" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://maps.yandex.ru/business/1.x http://maps.yandex.ru/schemas/business/1.x/business.xsd http://maps.yandex.ru/geocoder/1.x http://maps.yandex.ru/schemas/geocoder/1.x/geocoder.xsd http://maps.yandex.ru/psearch/1.x http://maps.yandex.ru/schemas/psearch/1.x/psearch.xsd http://maps.yandex.ru/search/1.x http://maps.yandex.ru/schemas/search/1.x/search.xsd http://maps.yandex.ru/web/1.x http://maps.yandex.ru/schemas/web/1.x/web.xsd http://maps.yandex.ru/search/internal/1.x http://maps.yandex.ru/schemas/search/internal/1.x/internal.xsd">
<GeoObjectCollection>
<metaDataProperty xmlns="http://www.opengis.net/gml">
<GeocoderResponseMetaData xmlns="http://maps.yandex.ru/geocoder/1.x">
<request>Sultanahmet Camii İç Yolları</request>
<found>2</found>
<results>10</results>
</GeocoderResponseMetaData>
</metaDataProperty>
<featureMember xmlns="http://www.opengis.net/gml">
<GeoObject xmlns="http://maps.yandex.ru/ymaps/1.x" xmlns:gml="http://www.opengis.net/gml" gml:id="1">
<metaDataProperty xmlns="http://www.opengis.net/gml">
<GeocoderMetaData xmlns="http://maps.yandex.ru/geocoder/1.x">
<kind>station</kind>
<text>Turkey, Istanbul, T1, Sultanahmet Tramvay İstasyonu</text>
<precision>other</precision>
<Address xmlns="http://maps.yandex.ru/address/1.x">
<country_code>TR</country_code>
<formatted>Istanbul, T1, Sultanahmet Tramvay İstasyonu</formatted>
<Component>
<kind>country</kind>
<name>Turkey</name>
</Component>
<Component>
<kind>province</kind>
<name>İstanbul</name>
</Component>
<Component>
<kind>locality</kind>
<name>Istanbul</name>
</Component>
<Component>
<kind>route</kind>
<name>T1</name>
</Component>
<Component>
<kind>station</kind>
<name>Sultanahmet Tramvay İstasyonu</name>
</Component>
</Address>
<AddressDetails xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">
<Country>
<AddressLine>Istanbul, T1, Sultanahmet Tramvay İstasyonu</AddressLine>
<CountryNameCode>TR</CountryNameCode>
<CountryName>Turkey</CountryName>
<AdministrativeArea>
<AdministrativeAreaName>İstanbul</AdministrativeAreaName>
<Locality>
<LocalityName>Istanbul</LocalityName>
<Thoroughfare>
<ThoroughfareName>T1</ThoroughfareName>
<Premise>
<PremiseName>Sultanahmet Tramvay İstasyonu</PremiseName>
</Premise>
</Thoroughfare>
</Locality>
</AdministrativeArea>
</Country>
</AddressDetails>
</GeocoderMetaData>
</metaDataProperty>
<description xmlns="http://www.opengis.net/gml">T1, Istanbul, Turkey</description>
<name xmlns="http://www.opengis.net/gml">Sultanahmet Tramvay İstasyonu</name>
<boundedBy xmlns="http://www.opengis.net/gml">
<Envelope>
<lowerCorner>28.967326 41.001841</lowerCorner>
<upperCorner>28.983783 41.014307</upperCorner>
</Envelope>
</boundedBy>
<Point xmlns="http://www.opengis.net/gml">
<pos>28.975555 41.008074</pos>
</Point>
</GeoObject>
</featureMember>
<featureMember xmlns="http://www.opengis.net/gml">
<GeoObject xmlns="http://maps.yandex.ru/ymaps/1.x" xmlns:gml="http://www.opengis.net/gml" gml:id="2">
<metaDataProperty xmlns="http://www.opengis.net/gml">
<GeocoderMetaData xmlns="http://maps.yandex.ru/geocoder/1.x">
<kind>other</kind>
<text>Turkey, İstanbul, Fatih, Sultanahmet Semti</text>
<precision>other</precision>
<Address xmlns="http://maps.yandex.ru/address/1.x">
<country_code>TR</country_code>
<formatted>İstanbul, Fatih, Sultanahmet Semti</formatted>
<Component>
<kind>country</kind>
<name>Turkey</name>
</Component>
<Component>
<kind>province</kind>
<name>İstanbul</name>
</Component>
<Component>
<kind>area</kind>
<name>Fatih</name>
</Component>
<Component>
<kind>other</kind>
<name>Sultanahmet Semti</name>
</Component>
</Address>
<AddressDetails xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">
<Country>
<AddressLine>İstanbul, Fatih, Sultanahmet Semti</AddressLine>
<CountryNameCode>TR</CountryNameCode>
<CountryName>Turkey</CountryName>
<AdministrativeArea>
<AdministrativeAreaName>İstanbul</AdministrativeAreaName>
<SubAdministrativeArea>
<SubAdministrativeAreaName>Fatih</SubAdministrativeAreaName>
<Locality>
<Premise>
<PremiseName>Sultanahmet Semti</PremiseName>
</Premise>
</Locality>
</SubAdministrativeArea>
</AdministrativeArea>
</Country>
</AddressDetails>
</GeocoderMetaData>
</metaDataProperty>
<description xmlns="http://www.opengis.net/gml">Fatih, İstanbul, Turkey</description>
<name xmlns="http://www.opengis.net/gml">Sultanahmet Semti</name>
<boundedBy xmlns="http://www.opengis.net/gml">
<Envelope>
<lowerCorner>28.938921 40.982047</lowerCorner>
<upperCorner>29.004804 41.031955</upperCorner>
</Envelope>
</boundedBy>
<Point xmlns="http://www.opengis.net/gml">
<pos>28.971863 41.007006</pos>
</Point>
</GeoObject>
</featureMember>
</GeoObjectCollection>
</ymaps>The geocoder response consists of a document in YMapsML format, which conforms to the XML schema https://geocode-maps.yandex.ru/docs/schemas/geocoder/1.x.
The response in JSON format
To get a response in JSON format, it is necessary to add the format parameter with the value json:
https://geocode-maps.yandex.ru/1.x/?format=json&apikey=Your API key&geocode=Sultanahmet+Camii+İç+Yolları&lang=en-USIn this case, the geocoder response will look like this:
Response:
{
"response": {
"GeoObjectCollection": {
"metaDataProperty": {
"GeocoderResponseMetaData": {
"request": "Sultanahmet Camii \u0130\u00e7 Yollar\u0131",
"found": "2",
"results": "10"
}
},
"featureMember": [
{
"GeoObject": {
"metaDataProperty": {
"GeocoderMetaData": {
"kind": "station",
"text": "Turkey, Istanbul, T1, Sultanahmet Tramvay \u0130stasyonu",
"precision": "other",
"Address": {
"country_code": "TR",
"formatted": "Istanbul, T1, Sultanahmet Tramvay \u0130stasyonu",
"Components": [
{
"kind": "country",
"name": "Turkey"
},
{
"kind": "province",
"name": "\u0130stanbul"
},
{
"kind": "locality",
"name": "Istanbul"
},
{
"kind": "route",
"name": "T1"
},
{
"kind": "station",
"name": "Sultanahmet Tramvay \u0130stasyonu"
}
]
},
"AddressDetails": {
"Country": {
"AddressLine": "Istanbul, T1, Sultanahmet Tramvay \u0130stasyonu",
"CountryNameCode": "TR",
"CountryName": "Turkey",
"AdministrativeArea": {
"AdministrativeAreaName": "\u0130stanbul",
"Locality": {
"LocalityName": "Istanbul",
"Thoroughfare": {
"ThoroughfareName": "T1",
"Premise": {
"PremiseName": "Sultanahmet Tramvay \u0130stasyonu"
}
}
}
}
}
}
}
},
"description": "T1, Istanbul, Turkey",
"name": "Sultanahmet Tramvay \u0130stasyonu",
"boundedBy": {
"Envelope": {
"lowerCorner": "28.967326 41.001841",
"upperCorner": "28.983783 41.014307"
}
},
"Point": {
"pos": "28.975555 41.008074"
}
}
},
{
"GeoObject": {
"metaDataProperty": {
"GeocoderMetaData": {
"kind": "other",
"text": "Turkey, \u0130stanbul, Fatih, Sultanahmet Semti",
"precision": "other",
"Address": {
"country_code": "TR",
"formatted": "\u0130stanbul, Fatih, Sultanahmet Semti",
"Components": [
{
"kind": "country",
"name": "Turkey"
},
{
"kind": "province",
"name": "\u0130stanbul"
},
{
"kind": "area",
"name": "Fatih"
},
{
"kind": "other",
"name": "Sultanahmet Semti"
}
]
},
"AddressDetails": {
"Country": {
"AddressLine": "\u0130stanbul, Fatih, Sultanahmet Semti",
"CountryNameCode": "TR",
"CountryName": "Turkey",
"AdministrativeArea": {
"AdministrativeAreaName": "\u0130stanbul",
"SubAdministrativeArea": {
"SubAdministrativeAreaName": "Fatih",
"Locality": {
"Premise": {
"PremiseName": "Sultanahmet Semti"
}
}
}
}
}
}
}
},
"description": "Fatih, \u0130stanbul, Turkey",
"name": "Sultanahmet Semti",
"boundedBy": {
"Envelope": {
"lowerCorner": "28.938921 40.982047",
"upperCorner": "29.004804 41.031955"
}
},
"Point": {
"pos": "28.971863 41.007006"
}
}
}
]
}
}
}The response in JSONP format
To get a response in JSONP format, set the format parameter to json and the callback parameter to the name of the function that will process the results. When using JSONP, the result is returned as a parameter of the function with the specified name.
Let's look at the request from the example above, but with the added
callback parameter:https://geocode-maps.yandex.ru/1.x/?format=json&callback=my_function&geocode=Sultanahmet+Camii+İç+Yolları&lang=en-USThe response will return the JSON object from the previous example, but as an argument of the function my_function:
my_function({
"response": {
"GeoObjectCollection": {
"metaDataProperty": {
"GeocoderResponseMetaData": {
"request": "Sultanahmet Camii İç Yolları",
"found": "1",
"results": "10"
...
});