HTTP request parameters

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

For example, to find out the coordinates of the building at the address "Kabasakal Caddesi, Istanbul, Turkey", we could send the following request to the geocoder:

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 response).

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

Note. If you exceed the daily request limit, the geocoder returns the status 429 instead of the result.

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

ParameterDescriptionExample
Required parameters
geocode

The address you want to geocode, or the geographical coordinates.

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

apikey

The key assigned in the Developer's Dashboard. Used only in the commercial version of the API.

apikey=Ahdb3kz...

Optional parameters
sco The order coordinates are specified in (only for reverse geocoding). Possible values:
  • longlat - Longitude, latitude (by 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

kind Type of toponym (only for reverse geocoding).

Acceptable values:

  • house - house or building
  • street - street
  • metro - subway station
  • district - city district
  • locality - locality (city, town, village, etc.)

Reverse geocoding:

kind=street

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
callback

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

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

callback=my_response_handler
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
[no-highlight[

Description

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

  • 0 – Do not restrict the search (by default).
  • 1 – Restrict.

Example

rspn=1]no-highlight]
parameter). If it is not limited, using the ll and spn parameters affects the order of results output; objects that are inside this area are given priority.

Record format

The ll parameter defines the longitude and latitude of the center of the area (in degrees), while spn defines its range (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 taken into account only if the kind parameter takes 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").

Format:

bbox=x1,y1~x2,y2

Note. If bbox and 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 either ll and spn or bbox parameters. Possible values:

  • 0 – Do not restrict the search (by default).
  • 1 – Restrict.
rspn=1
results

Maximum number of objects to return.

Default value: 10.

Maximum value: 100.

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

Locale.

Record format

lang=language_region, where

  • language — Two-letter language code. Specified in ISO 639-1 format. Sets the language for displaying names of geographical objects.
  • 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 (by default)
  • uk_UA — Ukrainian
  • be_BY — Belarusian
lang=en_US

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 can be placed either before or after the coordinates: "N39.889847, E32.810152" or "39.889847N, 32.810152E". 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 formatOrder of coordinatesExample
+-float, +-floatLongitude, latitude134.854, -25.828
float [direction] *
[no-highlight[

* [direction] - The letter designation for one of the four directions: N, E, W, S.

]no-highlight]
, float [direction]
AnyE134.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] Any25°49′41.1″S, 134°51′15.88″E
NMEAAny2549.67,S, 13451.26,E

* [direction] - The letter designation for 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>