Request

To receive a response about the location of a mobile device, send a POST request to the geolocation resource. Pass the data in XML format:

Yandex Locator processes the request data in the following order:

  1. Wi-Fi access points.
  2. Mobile network signals.
  3. IP address.

If Yandex Locator determines the location, it returns the response with the coordinates of the point and the accuracy radius. Otherwise you receive an error message.

The Yandex Locator API has a limit on the number of requests per second (RPS): up to 1800. It's calculated as the sum of requests from the client and from the server.

Standard request

Pass the data about the mobile device and its environment in the xml request parameter.

Host: api.lbs.yandex.net
POST /geolocation

xml=<ya_lbs_request>
  <common>
    <version>1.0</version>
    <api_key>ABM6WU0BAAAANfFuIQIAV1pUEYIBeogyUNvVbhNaJPWeM-AAAAAAAAAAAACRXgDsaYNpZWpBczn4Lq6QmkwK6g==</api_key>
  </common>
  <gsm_cells>
    <cell>
      <countrycode>250</countrycode>
      <operatorid>2</operatorid>
      <cellid>197403650</cellid>
      <lac>9900</lac>
      <signal_strength>-80</signal_strength>
      <age>1000</age>
    </cell>
  </gsm_cells>
  <wifi_networks>
     <network>
            <mac>2CD02D814C80</mac>
        <signal_strength>-68</signal_strength>
        <age>500</age>
     </network>
     <network>
            <mac>E4AA5DE28CD0</mac>
        <signal_strength>-60</signal_strength>
        <age>500</age>
     </network>
  </wifi_networks>
  <ip>
     <address_v4>95.108.173.231</address_v4>
  </ip>
</ya_lbs_request>


curl -X POST 'http://api.lbs.yandex.netapi.lbs.yandex.net/geolocation' -d 'xml=<ya_lbs_request><common><version>{{ version }}</version><api_key>ABM6WU0BAAAANfFuIQIAV1pUEYIBeogyUNvVbhNaJPWeM-AAAAAAAAAAAACRXgDsaYNpZWpBczn4Lq6QmkwK6g==</api_key></common><gsm_cells><cell><countrycode>250</countrycode><operatorid>2</operatorid><cellid>197403650</cellid><lac>9900</lac><signal_strength>-80</signal_strength><age>1000</age></cell></gsm_cells><wifi_networks><network><mac>2CD02D814C80</mac><signal_strength>-68</signal_strength><age>500</age></network><network><mac>E4AA5DE28CD0</mac><signal_strength>-60</signal_strength><age>500</age></network></wifi_networks><ip><address_v4>95.108.173.231</address_v4></ip></ya_lbs_request>'

Elements

Element Description Required
ya_lbs_request Root element. Yes
common Request metadata. Yes
version Yandex Locator API version: 1.0. Yes
api_key The Yandex Locator API access key. Yes
gsm_cells Contains one or more cell elements with the cell data. No
cell Contains ID codes of one cell and the signal level data. At least one element
countrycode Country code. Yes
operatorid Mobile network code. Yes
cellid Cell ID. Yes
lac Location code. Yes
signal_strength The signal strength measured at the location of the mobile device. A negative number expressed in decibel-milliwatts (dBm). The element is reserved for future use. No
age The time in milliseconds from the moment the mobile device obtains the data. The element is reserved for future use. No
wifi_networks Contains one or more network elements with data about Wi-Fi access points. No
network Contains the MAC address of the access point. May also contain data about the signal level. At least one element
mac The MAC address in character representation without separators. For example: 123456789ABC. Yes
signal_strength The signal strength measured at the location of the mobile device. A negative number expressed in decibel-milliwatts (dBm). The element is reserved for future use. No
age The time in milliseconds from the moment the mobile device obtains the data. The element is reserved for future use. No
ip Contains the address_v4 element. No
address_v4 The IP address of the mobile device assigned by the mobile internet carrier. If the IP address is missing or invalid, Yandex Locator uses the sender's address from the IP packet header. This address may be substituted by the proxy server the IP packet passed through. Yes

Request with compressed data

Compress the XML with data using the gzip utility and pass it in the request. Specify the Content-Type: multipart/from-data header and set any non-zero value to the gzip parameter.

In the request of the multipart/from-data type, include two parts:

  1. gzip: Indicator of the request with compressed data.
  2. xml: Parameter containing compressed XML data.

In each part of the request, specify the value of one parameter after the boundary separator and the Content-Disposition header that contains the parameter name. The parameter value must be separated from the preceding headers with an empty string.

Send a POST request to the geolocation resource.

POST /geolocation?gzip=1
Host: api.lbs.yandex.net
Accept-Encoding: identity
Content-Type: multipart/form-data; boundary=YANDEXLOCATORBOUNDARY
Content-length: 606

--YANDEXLOCATORBOUNDARY
Content-Disposition: form-data; name="gzip"

1
--YANDEXLOCATORBOUNDARY
Content-Disposition: form-data; name="xml"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary

COMPRESSED DATA
--YANDEXLOCATORBOUNDARY--


curl -X POST 'http://api.lbs.yandex.netapi.lbs.yandex.net/geolocation?gzip=1' -H 'Content-Type: multipart/form-data' -F xml=@data.xml.gz

Headers

Header Description
Accept-Encoding: identity Indicates the request contents should be accepted in any encoding.
Content-Type: multipart/form-data; boundary=_separator_ The request type for passing files inside an HTTP request. The boundary separator is an arbitrary string of Latin letters and numbers.
Content-length: _integer_ The length of the request in bytes starting from the second string after this header.
Content-Disposition: form-data; name="_parameter_name_" The request prefix for passing the parameter declared in name. Preceded by a separator. The parameter value is specified after the child headers and an empty string.
Content-Type: application/octet-stream Indicates the nested data is a file of an unspecified type.
Content-Transfer-Encoding: binary Indicates the content is binary data.
Previous
API
Next
Response
In this article: