HTTP request parameters

A request for the geocoder consists of an HTTP request sent to the URL

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:,+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:

Required parameters

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

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

Forward geocoding:


Reverse geocoding:



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


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:


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:



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.


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.


Geographical area for the object search.

The search can be limited to this area, or unlimited (depending on the value of the 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.


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:


Reverse geocoding:


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



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

It is ignored during reverse geocoding.


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.

Maximum number of objects to return.

Default value: 10.

Maximum value: 100.

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


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

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:,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] *

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

, 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]":

            <pos>134.854412 -25.828084</pos>