Courier coordinates

Logistics coordinators need to receive courier coordinates in real time in order to monitor order deliveries and depot visits, as well as to determine the estimated time of arrival (ETA).

Sources of coordinates

Coordinates can be sent to Track & Trace from a mobile app or a GPS tracker (see Preparing data), as well as via an API (needs to be set up by tech support). For example, sending coordinates via the API is convenient for companies that use their own mobile app.

Couriers can use both GPS trackers and the Yandex Courier app at the same time. The app lets couriers get information about orders, post comments and photos, and view their location on the map. The GPS tracker sends more accurate coordinates to Track & Trace than a smartphone.

Determining the source of coordinates

If coordinates come from multiple sources, you can specify which one should be used for displaying the courier route and calculating the ETA. You can set a source for the entire company or for individual couriers.

If the source of coordinates is set to a GPS tracker, then the app on the courier's smartphone doesn't receive coordinates from this GPS tracker and instead determines them itself. Smartphone coordinates aren't sent to Track & Trace in this case.

To set a coordinate source for a company, you need to contact support.

To set a coordinate source for a courier, use an API and pass the array of allowed_courier_position_sources parameter values in the request body. Possible values:

  • gps_tracker: From a GPS tracker.
  • app: From the Yandex Courier app.
  • s2s_api: Via the API.

If no parameter is set for the courier, the value set for the company is used.

By default, all coordinate sources are activated for the company, with no parameters set for individual couriers.

If the value of the allowed_courier_position_sources parameter is an empty array, coordinates are not sent to Track & Trace.

Getting coordinates from via the API

To transmit the courier's coordinates to the database, send a request to the push-positions-v3 resource.

In the request, specify:

  • courier_id and route_id: Courier and route IDs used in the requests to the Track & Trace API.

  • apikey: Company's API key. You can find the key in the company settings — check the API Key field.

In the request header, specify X-YaCourier-Signature — it must include the signature.

Warning

The signature is calculated using this algorithm. The calculation uses a 16-character secret (obtained from the client manager or support). The secret is not a signature.

Request:

cURL

curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-OAuth-token>" -H "X-YaCourier-Signature: <your-signature>" -X POST -d @<File_path_in_UTF-8_encoding> https://api.courier.yandex.net/api/v1/couriers/<courier-id>/routes/<route-id>/push-positions-v3?apikey=<apikey>

File

{
"positions": [
        {
        "accuracy": 5,
        "point": {
            "lat": 59.987543,
            "lon": 30.353874
            },
        "timestamp": 1711964409
        }
    ]
}

cURL

curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-OAuth-token>" -H "X-YaCourier-Signature: <your-signature>" -X POST -d '{"positions": [{"accuracy": 5, "point": {"lat": 59.987543, "lon": 30.353874}, "timestamp": 1711964409}]}' https://api.courier.yandex.net/api/v1/couriers/<courier-id>/routes/<route-id>/push-positions-v3?apikey=<apikey>

Result:

{}
Contact support