HTTP geocoding request

Sets the task to forward or reverse geocoding.

  1. Request format
  2. Format for geographical coordinates in the request
  3. Coordinates of the request in the geocoder's response
  4. Request example

Request format

https://geocode-maps.yandex.ru/1.x
 ? geocode=<string>
 & apikey=<string>
 & [sco=<string>]
 & [kind=<string>]
 & [rspn=<boolean>]
 & [ll=<number>, <number>]
 & [spn=<number>, <number>]
 & [bbox=<number>,<number>~<number>,<number>]
 & [format=<string>]
 & [skip=<integer>]
 & [lang=<string>]
 & [callback=<string>]
geocode *
Address or geographical coordinates of the object being searched for. The specified data determines the type of geocoding:
  • If an address is specified, it is converted to object coordinates. This process is called forward geocoding.
  • If coordinates are specified, they are converted to the object's address. This process is called reverse geocoding.

Several formats for entering coordinates are available.

apikey *The key issued in the Developer's Dashboard.
scoOnly if the geocode parameter sets the coordinates. Order of coordinates. Possible values:
  • longlat — Longitude, latitude.
  • latlong — Latitude, longitude.

Default value: longlat.

kindOnly if the geocode parameter sets the coordinates. The type of required toponym.
List of accepted values:
  • house — house
  • street — street
  • metro — subway station
  • district — city district
  • locality — locality (city, town, village, etc.)
If omitted, the API will choose the type of the toponym automatically.
rspn

Flag indicating whether the search scope should be restricted to the specified area. The area is defined by the ll and spn or bbox parameters. Possible values:

  • 0 — Do not restrict search.
  • 1 — Restrict search.

Default value: 0.

llLongitude and latitude of the center of the search area. The span of the search area is set in the spn parameter.
Note. If the geocode parameter sets the coordinates, the ll parameter is ignored.
spn

The span of the search area. The center of the area is set in the ll parameter.

Set by two numbers:
  • the first is the difference between the maximum and minimum longitude of the area;
  • the second is the difference between the maximum and minimum latitude.
Note. If the geocode parameter sets the coordinates and the kind parameter value is district, the spn parameter is ignored.
bbox

An alternative method for setting the search area.

The borders are defined as the geographical coordinates of the lower-left and upper-right corners of the area (in the order "longitude, latitude").

Record format:

bbox=x1,y1~x2,y2
Note. If bboxand ll+spn are used simultaneously, the bbox parameter takes priority.

Ignored if the geocode parameter sets the coordinates.

format

Geocoder's response format

  • xml — Results are returned as a YMapsML document.
  • json — Results are returned in JSON format.

Default value: xml.

skipThe number of objects to skip in the response, starting from the first one.

Default value: 0.

lang

Language of the response and regional settings of the map.

Record format

lang=language_region, where
  • language — Two-letter language code. Specified in ISO 639-1 format. Sets the language for displaying the names of geographical features.
  • region — Two-letter country code. Specified in ISO 3166-1 format. Determines regional settings.

List of supported values:

  • tr_TR — Turkish (only for maps of Turkey).
  • en_RU — response in English, Russian map features;
  • en_US — response in English, American map features;
  • ru_RU — Russian (default);
  • uk_UA — Ukrainian;
  • be_BY — Belarusian.

Default value: ru_RU.

callback

The name of the JavaScript function that returns the geocoder's response (in accordance with JSONP conventions).

This parameter is accepted only if the response is returned in JSON format.

geocode *
Address or geographical coordinates of the object being searched for. The specified data determines the type of geocoding:
  • If an address is specified, it is converted to object coordinates. This process is called forward geocoding.
  • If coordinates are specified, they are converted to the object's address. This process is called reverse geocoding.

Several formats for entering coordinates are available.

apikey *The key issued in the Developer's Dashboard.
scoOnly if the geocode parameter sets the coordinates. Order of coordinates. Possible values:
  • longlat — Longitude, latitude.
  • latlong — Latitude, longitude.

Default value: longlat.

kindOnly if the geocode parameter sets the coordinates. The type of required toponym.
List of accepted values:
  • house — house
  • street — street
  • metro — subway station
  • district — city district
  • locality — locality (city, town, village, etc.)
If omitted, the API will choose the type of the toponym automatically.
rspn

Flag indicating whether the search scope should be restricted to the specified area. The area is defined by the ll and spn or bbox parameters. Possible values:

  • 0 — Do not restrict search.
  • 1 — Restrict search.

Default value: 0.

llLongitude and latitude of the center of the search area. The span of the search area is set in the spn parameter.
Note. If the geocode parameter sets the coordinates, the ll parameter is ignored.
spn

The span of the search area. The center of the area is set in the ll parameter.

Set by two numbers:
  • the first is the difference between the maximum and minimum longitude of the area;
  • the second is the difference between the maximum and minimum latitude.
Note. If the geocode parameter sets the coordinates and the kind parameter value is district, the spn parameter is ignored.
bbox

An alternative method for setting the search area.

The borders are defined as the geographical coordinates of the lower-left and upper-right corners of the area (in the order "longitude, latitude").

Record format:

bbox=x1,y1~x2,y2
Note. If bboxand ll+spn are used simultaneously, the bbox parameter takes priority.

Ignored if the geocode parameter sets the coordinates.

format

Geocoder's response format

  • xml — Results are returned as a YMapsML document.
  • json — Results are returned in JSON format.

Default value: xml.

skipThe number of objects to skip in the response, starting from the first one.

Default value: 0.

lang

Language of the response and regional settings of the map.

Record format

lang=language_region, where
  • language — Two-letter language code. Specified in ISO 639-1 format. Sets the language for displaying the names of geographical features.
  • region — Two-letter country code. Specified in ISO 3166-1 format. Determines regional settings.

List of supported values:

  • tr_TR — Turkish (only for maps of Turkey).
  • en_RU — response in English, Russian map features;
  • en_US — response in English, American map features;
  • ru_RU — Russian (default);
  • uk_UA — Ukrainian;
  • be_BY — Belarusian.

Default value: ru_RU.

callback

The name of the JavaScript function that returns the geocoder's response (in accordance with JSONP conventions).

This parameter is accepted only if the response is returned in JSON format.

* Required

Format for geographical coordinates in the request

Geographical coordinates in the geocode parameter are set sequentially in one of the following formats:

Record format Order of coordinates Example
+-float, +-float Longitude, latitude 134.854, -25.828

float [direction] , float [direction] *

 Any E134.854, S25.828

134.854E, 25.828S
+-deg° mm' ss", +-deg° mm' ss" Latitude, longitude -25°49′41.1″, 134°51′15.88″
deg° mm' ss" [direction], deg° mm' ss" [direction] * Any 25°49′41.1″S, 134°51′15.88″E
NMEA Any 2549.67,S, 13451.26,E
Record format Order of coordinates Example
+-float, +-float Longitude, latitude 134.854, -25.828

float [direction] , float [direction] *

 Any E134.854, S25.828

134.854E, 25.828S
+-deg° mm' ss", +-deg° mm' ss" Latitude, longitude -25°49′41.1″, 134°51′15.88″
deg° mm' ss" [direction], deg° mm' ss" [direction] * Any 25°49′41.1″S, 134°51′15.88″E
NMEA Any 2549.67,S, 13451.26,E

* [direction] - The letter designation of one of the four directions: N, E, W, S. Spaces are allowed between letters and coordinates

Spaces, commas, or semicolons can be used as delimiters. Spaces are allowed on either side of the delimiter character.

Note. The ";" character should be encoded as "%3B".

Coordinates of the request in the geocoder's response

The geocoder returns the given coordinates in the metaDataProperty/GeocoderResponseMetaData/Point/pos element. Coordinates are set in the format “[longitude] [latitude]”:
<metaDataProperty>
  <GeocoderResponseMetaData>
    <request>E134.854,S25.828</request>
    <found>1</found>
    <results>10</results>
    <Point>
      <pos>134.854412 -25.828084</pos>
    </Point>
  </GeocoderResponseMetaData>
</metaDataProperty>

Request example

To determine the coordinates of the building at the address "Kabasakal Caddesi, Istanbul, Turkey", send the following request:

https://geocode-maps.yandex.ru/1.x/?apikey=Your API key&geocode=Kabasakal+Caddesi,+Istanbul,+Turkey&lang=en_US

The geocoder's response will contain the geographical coordinates of the building, along with any additional information about the found object (see The geocoder response).

For reverse geocoding, the request specifies the coordinates of the object being searched for:

https://geocode-maps.yandex.ru/1.x/?apikey=Your API key&geocode=28.978798,41.006543&lang=en_US

See the Examples section for more examples.