HTTP request parameters

A request to the geocoder consists of an HTTPS request sent to the URL https://geocode-maps.yandex.ru/1.x/?lang=tr-TR.

For 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/?geocode=Kabasakal+Caddesi,+Istanbul,+Turkey&lang=en_US

In response, the geocoder returns the geographical coordinates of the building, along with any additional information about the found object (see the request results).

For reverse geocoding, the request specifies the coordinates of the object you are looking for, and the response returns its address.

Note. If the daily request limit is exceeded, the service returns the status 429 instead of the geocoding results.

The table shows a list of parameters for the HTTP request:

Parameter Description Example
Required parameters
geocode

Address or geographical coordinates of the object being searched for. Required parameter.

Coordinates can be set in one of the formats described below.

Forward geocoding:

geocode=Kabasakal+Caddesi,+Istanbul,+Turkey

Reverse geocoding:

geocode=28.98017,41.008434
Optional parameters

apikey

The key issued in the Developer's Dashboard. Only used in the commercial version of the API.

apikey=Ahdb3kz...

Setting the coordinate order
sco The order of coordinates in requests (only for reverse geocoding). Possible values:
  • longlat— Longitude, latitude (default).
  • latlong — Latitude, longitude.

Regardless of the value of this parameter, the geocoder response always returns the coordinates in the order “longitude latitude”.

Reverse geocoding:

sco=latlong

Restricting the objects returned by the geocoder

kind

Type of toponym (only for reverse geocoding).
List of accepted values:
  • house - house
  • street - street
  • metro - subway station
  • district - city district
  • locality - locality (city, town, village, etc.)
Reverse geocoding:

kind=street

Restricting responses to the geographical area
ll+spn

Geographical area for the object search.

The search can be limited to this area, or unlimited (depending on the value of the rspn parameter). In the latter case, the specified area can be included in the ranking.

Record format

The ll parameter defines the longitude and latitude of the center of the area, and spn defines its length (in degrees).

The span of the area is defined by two numbers; the first is the difference between the maximum and minimum longitude of the area, and the second is the difference between the maximum and minimum latitude.

Reverse geocoding

For reverse geocoding, the ll parameter is ignored, and spn is used only if the kind parameter accepts one of the following values: house, street, locality or metro.

Forward geocoding:

ll=28.98017,41.008434&spn=0.552069,0.400552

Reverse geocoding:

spn=0.552069,0.400552&kind=street
bbox

An alternative method for setting the search area (see ll+spn).

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

Record format:

bbox=x1,y1~x2,y2

Note. If bboxand ll+spn are both set at the same time, the bbox parameter takes priority.

It is ignored during reverse geocoding.

bbox=36.6,54.6~38.6,56.6
rspn

Restricts the search scope to the area defined using ll and spn or bbox parameters. Possible values:

  • 0 - Do not restrict the search (by default).
  • 1 - Restrict.
rspn=1
Geocoder response format
format

The format for the geocoder's response:

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

Default value: xml.

format=json
skip The number of objects to skip in the response (starting from the first one). Default value: 0. skip=3
lang

Response language.

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 — United States
  • en_US — American English
  • ru_RU — Russian (default)
  • uk_UA — Ukrainian
  • be_BY — Belarusian
lang=en_US
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.

callback=my_response_handler

Formats for geographical coordinates

In the HTTP request to the geocoder, geographical coordinates are set using the geocode parameter. The coordinate values are listed sequentially and separated by a space, comma, or semicolon. In addition, any number of spaces is allowed on either side of the separators.
Note. The ";" character should be encoded as "%3B".

To indicate the sign for coordinates, you can use the "+" and "-" symbols, or letters corresponding to the hemisphere (using the "+" symbol is optional). For example, N (Northern latitude) and E (Eastern longitude) indicate positive coordinates, while W (Western longitude) and S (Southern latitude) indicate negative coordinates.

Letters may be specified either before or after the coordinates: "N39.889847, E32.810152" or "39.889847 N, 32.810152 E". The letters can also be separated by a space: "N 39.889847, E 32.810152".

Request example for reverse geocoding:
https://geocode-maps.yandex.ru/1.x/?geocode=E134.854,S25.828&lang=en-US
The list below shows acceptable formats for expressing geographical coordinates:
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.

The geocoder returns the given coordinates in the metaDataProperty/GeocoderResponseMetaData/Point/pos element 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>