Overview
Dynamic Layers is a RESTful API for ingesting dynamic spatial data into the RapidSOS Platform.
Dynamic spatial layer data consists of a series of locations for an object, for instance a body camera, representing the object’s movement within a given map layer.
Pre-Requisites
Map Layer Management API - The implementation and use of the Map Layer Management is required for use with dynamic layers.
Authentication
This interface is authenticated via TWO-LEGGED OAUTH2 (2LO). This entails retrieving a short-lived OAuth 2.0 access token granted using application client credentials. The token is valid for authenticating requests to the API for one hour, after which a new token for future requests will need to be fetched. Details for retrieving and using one of these tokens are described below.
Refer to the Dynamic Layers API Reference documentation for additional details.
GETTING AN AUTHENTICATION TOKEN
POST /OAUTH/TOKEN/
Request
- Headers
- Content-Type: application/x-www-form-urlencoded
- Body Parameters
- client_id: Client ID of an application authorized to use the service
- client_secret: Client secret of an application authorized to use the service
- grant_type: This parameter should be hardcoded to client_credentials
Response
- access_token: Short-lived OAuth 2.0 access token
- token_type: Token type descriptor, in this case BearerToken
- issued_at: UNIX timestamp in UTC of the time when the token was issued
- expires_in: Number of seconds after the issued_at time that the access token will expire (defaults to 3600 seconds)
USING AN AUTHENTICATION TOKEN
To authenticate requests using an access token, requests must include an Authorization header set to the value Bearer <ACCESS-TOKEN> where <ACCESS-TOKEN> is substituted for the retrieved access token.
TEST CREDENTIALS
Please contact SUPPORT@RAPIDSOS.COM for test credentials.
Request Structure
Request
- Method: POST
- URL: https://api-sandbox.rapidsos.com/v1/dynamic-layers
- Headers
- Content-Type: application/json
- Accept: application/json
- Body
- (See below)
Request Body
The Dynamic Layers API uses standard POST requests.
Create dynamic spatial object
POST
/
Parameters
- No parameters
Example request body
{
"external_id": "6f95013b-7bf8-49ce-b24f-9a935e49b324",
"latitude": 40.679074,
"longitude": -73.979538,
"layer_key": "first_responders",
"attributes": {
"name": "Michelle Davies",
"role": "Detective",
"unit_id": "xyz123"
}
}
During the provisioning process, RapidSOS will register a layer and provide the partner with a unique layer_key. The process is as follows:
- RapidSOS approves and creates a layer
- Partner is provided access to the Map Layer Management and Dynamic Layers APIs via a single set of credentials for both services.
- Layer keys are retrieved from the Map Layer Management API by the Partner and included in the request body of any payloads sent to the Dynamic Layers API.
IMPORTANT: The layer_key is the key that must be used when sending inbound dynamic object locations. It is a unique and immutable value representing the layer to which the object belongs.
Note: Each payload represents where an object is at a specific point in time. The object’s current location is understood to be the most recently received payload.
Attributes will vary based on layer. The Map Layer Management API returns a JSON schema field indicating the structure of object attributes. For example, for the above attributes block, the spatial layer will have the following attributes schema:
{
"name":{
"required":true,
"title":"Name",
"type":"string"
},
"role":{
"required":true,
"title":"Role",
"type":"string"
},
"unit_id":{
"required":true,
"title":"Unit ID",
"type":"string"
}
}Responses and Values
|
Code |
Description |
Example Value |
|
202 |
Dynamic object accepted |
|
|
400 |
Bad Request. This occurs if the request payload has missing or invalid fields, or if the layer_key provided is not recognized. |
{ "detail": "string" } |
|
401 |
Unauthorized. This occurs if we are unable to identify requesting credentials. |
{ "detail": "string" } |
|
403 |
Access Forbidden. This occurs if the layer_key provided does not match a layer to which the requesting source has access. |
{ "detail": "string" } |
Schemas
Refer to the Dynamic Layers API Reference documentation for detailed information on available schemas.
Available schemas include:
RequestPayload
- external_id - (Required) An external unique ID for identifying the specific node f (i.e. first responder, defibrillator) the coordinates represent, as a string. Each external_id should be unique for each layer.
- Example: 6f95013b-7bf8-49ce-b24f-9a935e49b324
- latitude - (Required) The latitude of the dynamic object payload, as a number.
- Example: 40.679074
- longitude - (Required) Longitude of the dynamic object payload, as a number.
- Example: -73.979538
- layer_key - (Required) Key of the spatial layer to which the object belongs, as a string.
- Example: first_responders_police
- attributes - Attributes of the spatial object. The contents of this section will vary depending on the spatial layer to which the object belongs, as well as the information available for that object.
- Example: OrderedMap { "name": "Michelle Davies", "role": "Detective", "unit_id": "xyz123" }
ErrorResponse
- detail - Error message, as a string.
Additional Reference
- Dynamic Layers API Reference - The Open API specification for the Dynamic Layers API.
- Map Layer Management API Reference - The Open API specification and reference content for map layer management which allows external users the capability to manage their Spatial Layer objects in RapidSOS.