External geolocation API

Introduction

Cyke is the homebrewed delivery order tool from Cargonautes (ex OLVO). It is also used by dozens of companies in Europe. Cyke uses geolocation tracked from the messenger phone to provide precise information both to the dispatch and recipients of deliveries, especially to compute live ETAs.

This API is a way for GPS tracking solutions to integrate with Cyke and provide the geolocation of bike. Cyke will use it instead of the messenger position tracked from the phone. This provides a more precise geolocation, saving phone battery at the same time.

The positions sent through this API will be stored on Cyke only when the bike linked to the tracker is in use by a messenger with an active round.

Environments

The Cyke API is available directly on the Cyke main production server at https://www.cyke.io/.

If you need to develop an integration and do not want your tests to interfere with the production data, you may ask for an access to a test environment. Please send us an email at cyke@cargonautes.fr.

Test server specific features:

• It is available at https://staging.cyke.io/
• It never send emails nor text messages since deliveries are fake. (This means you cannot ask for a new password using the “Forgotten password feature”)

Geolocation Entity

A Geolocation represents the position of a bike at a given timestamp.

Name	Type	Description
timestamp	timestamp	The time at which the position was reported. If blank, Cyke will store the API call time instead.
latitude	float	Mandatory. The latitude of the vehicle.
longitude	float	Mandatory. The latitude of the vehicle.
provider	string	Mandatory. A name you must provide to identify yourself as a tracker provider. Ask us it you don’t know which name you should use.
tracker_id	integer	The identifier of the tracker in your system. This could be useful for debugging.

API Requests

Creating a geolocation

POST /external/vehicles/_vehicle_id_/geolocations

You may find the vehicle_id in the Cyke app, on the vehicle page, under the attribute “External ID”. If you have difficulties, please get in touch with us at cyke@cargonautes.fr

Code examples

curl

curl --location --request POST '<URL>/external/vehicles/_vehicle_id_/geolocations' \
--header 'Content-Type: application/json' \
--data-raw '{
  "provider": "_your_provider_id_",
  "tracker_id": "23164864631",
  "latitude": 48.8,
  "longitude": 2.32,
  "timestamp": "2019-09-04T12:00:00.000+02:00"
}'

ruby

require "uri"
require "net/http"
require "json"

url = URI("https://<URL>/external/vehicles/_vehicle_id_/geolocations")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"

payload = {
  "provider": "_your_provider_id_",
  "tracker_id": "23164864631",
  "latitude": 48.8,
  "longitude": 2.32,
  "timestamp": "2019-09-04T12:00:00.000+02:00"
}

request.body = payload.to_json
response = https.request(request)
puts response.read_body

Response

The response should be 200 (OK) with an empty body.

If the vehicle id given in the path was not recognized, the response will be 404 (Not Found).

If there is an error during the geolocation creation, the response will be 422 (Unprocessable Entity).

If you exceed the rate limiting of 1 request per second for each tracker, the response will be 429 (Too Many Requests).