This API is available for developer preview and may be changed or removed at any time without notice.

Events

The Events API allows developers to send telemetry events to Mapbox. These events usually originate from mobile or embedded devices and depict. The events may be realtime, with only a short time span passing between event creation and sending them to Mapbox, or historical, with a braoder time span passed and the events for example being backfilled from an existing events repository.

URL

The Events API can be used by sending POST requests with a JSON body to the following URL:

https://api.mapbox.com/events/v2?access_token=<your access token>

Here is an example request with curl. In this case, we are sending events as events.json per the Body format section below:

curl -X POST \
  --header "Content-Type:application/json" \
  -d @events.json \
  "https://api.mapbox.com/events/v2?access_token=<access_token>"

Parameters

parameter required? description
access_token required Mapbox Access Token

Request body format

The body must be in JSON format. It is an array with event objects. You may at maximum send 1000 events per request. You must at minimum send one event per request. The size of the request body may not surpass 1 MB.

The following event types exist:

  • location

Location event

A location event denotes a position at a specific time.

key required? example values description
event required location The type of event must be location
source required my-company-product, default The source value helps to determine different types of event sources, helping Mapbox to differently handle them. If you have not discussed a source identifier with Mapbox, please use the generic default source
created required 2016-02-12T03:21:55+00:00, 1455332428 The time at which the event was recorded. This may either be an ISO 8601 string or Unix time integer in milliseconds
sessionId required F312C8B0-D1FE-11E5-AAB0-3453A4143A20 A string identifier shared among events for the same trip. We recommend using UUIDs
lat required 10.0123898123 The latitude as float when the event was recorded
lng required 53.1239892108 The longitude as float when the event was recorded
altitude optional 12.0811 Altitude as float in meters. Can be negative.

Location event example

[
  {
      "event": "location",
      "source": "default",
      "created": "2016-02-12T03:21:55+00:00",
      "sessionId": "19ab383e28644f93b56f50e0beb7216f",
      "lat": 10.0123898123,
      "lng": 53.1239892108,
      "altitude": 12.0811
  }
]

Responses

On success, the server responds with an HTTP status code 204 No Content and no response body.

On error, the server responds with an HTTP status code denoting the error, as explained in the table below. The response body may include a JSON object with a message property, explaining the error.

HTTP status code comment
204 Success case
401 Unauthorized request, usually because of invalid access_token query parameter
422 Invalid message body, check the types and required properties of the events you sent

Limits

Per request you may send up to 1000 events and a maximum body size of 1 MB. There is no rate limiting.