Skip to main content

RAD-E (RapidSOS Additional Data) Enhanced2.0.0

RapidSOS Additional Data Enhanced API provides a RESTful JSON interface for querying additional data from various sources. Data from these sources is queried by phone number. It can also be queried by source-specific identifiers, such as MedicAlert ID.

Overview

The RAD (RapidSOS Additional Data) Enhanced API provides a RESTful interface for querying additional data from various sources. Data from these sources is queried by phone number. It can also be queried by unique identifiers associated with the owner of the data, such as their phone number or MedicAlert ID.

All developers should listen to this video from our April 2020 Webinar with details on how to develop against the API, best practices, and general API behavior:

 

IMPORTANT: It is strongly recommended that when integrating this API, fields should not be hard-coded. This is because it assumes that information which should be flexible is actually fixed and unchanging. It is best practice to develop a UI renderer based on our auto-rendering schema language to allow for generating UI components native to your software for any data fields that might be added, updated, etc. for any source.

 

Additional Data

All available sources of additional data provided to RapidSOS that your integration has been approved to receive will be made available using the RAD Enhanced endpoint.

 

Requesting Data

 

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.
 

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.
 

RAD Session Request

Requests for RAD Session Data are made using POST requests. The request body specifies the search criteria for the query.
 

Request Structure

 

Request

  • Method: POST
  • URL: /v2/emergency-data/session
  • Headers
    • Content-Type: application/json
    • Accept: application/json
  • Body
    • (See Below)
       

Request Body

The request body consists of a JSON dictionary containing the key, query.

The value of query must be a URI specifying the query type and value. Optionally, a meta request can be made for additional metadata (boolean: default False) . Send this flag in your request to include the display schema for the data returned which can be used for implementing auto-renderer UI parsers for the data.

Set to True as shown in the below example body to make this type of request.

 

Request Query URI

Query URIs are specified using the format topic-type://topic-value.

Some currently supported topic-types include:

tel: Query by caller ID
xxxxxx-id: Query by Specific ID

For example, maf-id for a medicalert ID can get queried with xxxxxx-id

 

Request with Metadata

Set to True as shown in the below example body to make this type of request.

Request by Caller ID (with the “meta”) :

POST /v2/emergency-data/session

Body:
{
  "query": "tel://19999999999",
  “meta”: true
}

 

 

Examples

Request body for request by Caller ID:

{
  "query": "tel://19999999999"
}
Request body for request by Specific ID:
{
  "query": "xxxx-id://999999"
}

 

Response Structure

The response from RAD is a json dictionary, keyed by each data source.
 

 

Data Sources

The available data sources allow a pre-defined "display" schema for data received by RapidSOS Portal. This dynamic schema allows it to automatically infer how these elements should be rendered.

 

 

Data Sources Available

The following list contains reference links for each available Data Source. Select the Data Source name from the list to view additional details about that source.

(In alphabetical order)

 

 

Rendering Schema and Data

The schema is defined per data source and dictates field ordering, labeling, formatting, etc. allowing for the automatic processing and rendering of the many new data types without the need for new UI development work every time a new data set is added.

 

Auto Generate Components from Data and Schema

The library takes a data object and a display schema as its input and return UI components representing those data points as defined by the display schema.

 

Text, Link, and Timestamp Support

The library can support rendering data as either text, a URL link, a human readable timestamp, hidden, dates and images. The criteria for rendering based on the schema is as follows:

type: string

format: web-url 

Recommended UI Element Type: clickable link (optional)

Sample web-url:

{
  “link_example”: {
    “type”: “string”,
    “format”: “web-url”
  }
}

 

type: integer

format: timestamp

UI: ISO80 Datestring

Sample timestamp:

{
  “timestamp_example”: {
    “type”: “integer”,
    “format”: “timestamp”
  }
}

 

type: integer, number, or string

format: None specified. This can optionally be text.

UI: text

Sample plain text:

{
  “plain_text_example”: {
    “type”: “string”
  }
}

 

Object Rendering

The library supports rendering fields with nested objects. The display schema defines these fields as an object and defines a display schema for each nested field within it. These nested fields cannot be objects or arrays. They must be strings or numbers.

Sample nested object data and display schema:

Data

{
  “object_field_example”: {
    “nested_simple_field”: 55
  }
}

 

Display Schema

{
  “object_field_example”: {
    “type”: “object”,
     “properties”: {
       “nested_simple_field”: {
          “type”: “integer”
       }
     }
  }
}

 

Array Rendering

The library can support rendering a field whose value is a list of values. These values can be any strings, numbers, or objects.

Generated UI components should provide a visual indicator separating each element of the list from one another.

Sample array data and display schema:

Data

{
  “array_field_example”: [1, 2, 3]
}
Display Schema
{
  “array_field_example”: {
    “type”: “array”,
     “items”: {
        “type”: “integer”
     }
  }
}

 

Ordered Components

The display schema defines a propertiesOrder attribute that defines the expected order in which each property is meant to be rendered. Your renderer should use this ordered list defined in the attribute to determine the order in which to render all properties within any object in the schema.

 

 

Example Schema

The following is an illustrative example of a fictitious ABC Corporation schema defining all required top-level attributes as well as at least one field of each of the types supported:

{
  "$schema": "http://json-schema.org/example-01/schema#",
  "type": "object",
  "title": "ABC Corporation Crash Detection",
  "propertiesOrder": ["id", "datetime", "location", "vehicle", "impacts", "airbags", "seats", "contacts"],
  "properties": {
    "id": {
      "type": "string",
      "title": "Crash ID"
    },
    "datetime": {
      "type": "integer",
      "format": "timestamp",
      "title": "Crash Time"
    },
    "location": {
      "type": "object",
      "title": "Crash Location",
      "propertiesOrder": ["latitude", "longitude", "timestamp", "speed", "bearing"],
      "properties": {
        "timestamp": {
          "type": "integer",
          "format": "timestamp",
          "title": "Location Time"
        },
        "latitude": {
          "type": "number",
          "title": "Latitude"
        },
        "longitude": {
          "type": "number",
          "title": "Longitude"
        },
        "bearing": {
          "type": "number",
          "title": "Bearing (In Degrees)"
        },
        "speed": {
          "type": "number",
          "title": "Speed (In M/S)"
        }
      }
    },
    "vehicle": {
      "type": "object",
      "title": "Vehicle Information",
      "propertiesOrder": ["make", "model", "color", "year", "vin"],
      "properties": {
        "vin": {
          "type": "string",
          "title": "Vin #"
        },
        "make": {
          "type": "string",
          "title": "Manufacturer"
        },
        "model": {
          "type": "string",
          "title": "Model"
        },
        "year": {
          "type": "string",
          "title": "Year"
        },
        "color": {
          "type": "string",
          "title": "Color"
        }
      }
    },
    "seats": {
      "type": "array",
      "title": "Seat Occupancy",
      "items": {
        "type": "object",
        "propertiesOrder": ["occupancy", "belt", "side", "row"],
        "properties": {
          "row": {
            "type": "integer",
            "title": "Seat Row"
          },
          "side": {
            "type": "string",
            "title": "Seat Side"
          },
          "occupancy": {
            "type": "string",
            "title": "Occupancy"
          },
          "belt": {
            "type": "string",
            "title": "Seatbelt Status"
          }
        }
      }
    },
    "airbags": {
      "type": "array",
      "title": "Airbag Statuses",
      "items": {
        "type": "object",
        "propertiesOrder": ["name", "deployed"],
        "properties": {
          "name": {
            "type": "string",
            "title": "Airbag Name"
          },
          "deployed": {
            "type": "string",
            "title": "Deployment Status"
          }
        }
      }
    },
    "impacts": {
      "type": "array",
      "title": "Vehicle Impacts",
      "items": {
        "type": "object",
        "propertiesOrder": ["front_crash", "driver_side_crash", "pass_side_crash", "rear_crash", "rollover", "sequence"],
        "properties": {
          "sequence": {
            "type": "integer",
            "title": "Impact Sequence"
          },
          "front_crash": {
            "type": "string",
            "title": "Front Crash Detected"
          },
          "driver_side_crash": {
            "type": "string",
            "title": "Driver Side Crash Detected"
          },
          "pass_side_crash": {
            "type": "string",
            "title": "Passenger Side Crash Detected"
          },
          "rear_crash": {
            "type": "string",
            "title": "Rear Crash Detected"
          },
          "rollover": {
            "type": "string",
            "title": "Rollover Detected"
          }
        }
      }
    },
    "contacts": {
      "type": "array",
      "title": "Emergency Contacts",
      "items": {
        "type": "object",
        "propertiesOrder": ["name", "phone_number", "note"],
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "phone_number": {
            "type": "string",
            "title": "Phone",
            "format": "phone-number"
          },
          "note": {
            "type": "string",
            "title": "Note"
          }
        }
      }
    }
  }
}

 

Code Sample

A full example using curl on the command line is below. You will need to replace [CLIENT ID] and [CLIENT SECRET] in the script with valid credentials for the RapidSOS Sandbox environment.

#!/bin/sh

 

NOTE: This script requires jq for json parsing: https://stedolan.github.io/jq/

server='https://api-sandbox.rapidsos.com'
client_id='[CLIENT ID]'
client_secret='[CLIENT SECRET]'
caller_id='19999999999'
maf_id='999999'
echo '########### 1 - GET AUTH TOKEN'
endpoint=$server/oauth/token
method='POST'
payload="client_id=$client_id&client_secret=$client_secret&grant_type=client_credentials"
response=$(curl -s -X $method $endpoint -d "$payload" | jq '.')
token=$(echo $response | jq -r '.access_token')
auth_header="Authorization: Bearer $token"
echo ENDPOINT: $endpoint
echo METHOD: $method
echo PAYLOAD: '<client credentials>'
echo RESPONSE:
echo $response | jq .
echo AUTH TOKEN: $token
echo
echo '########### 2 - GET DATA BY CALLER ID'
endpoint="$server/v2/emergency-data/session"
method='POST'
content_type="application/json"
payload="{\"query\": \"tel://$caller_id\"}"
response=$(curl -s -X $method $endpoint  -H "accept: $content_type" -H "Content-Type: $content_type" -H "$auth_header" -d "$payload" | jq '.')
echo ENDPOINT: $endpoint
echo METHOD: $method
echo RESPONSE:
echo $response | jq .
echo
echo '########### 3 - GET DATA BY MAF ID'
endpoint="$server/v2/emergency-data/session"
method='POST'
content_type="application/json"
payload="{\"query\": \"maf-id://$maf_id\"}"
response=$(curl -s -X $method $endpoint  -H "accept: $content_type" -H "Content-Type: $content_type" -H "$auth_header" -d "$payload" | jq '.')
echo ENDPOINT: $endpoint
echo METHOD: $method
echo RESPONSE:
echo $response | jq .
echo

 

Additional Considerations

The following considerations should be reviewed before implementing the RapidSOS Additional Data (RAD-E) solution:

  • Uber data: we do not receive differentiation regarding if the driver or rider triggered the alarm 
  • There is not always additional data available for a call
  • Regarding data retention and privacy, the data we provide is all voluntarily 
  • The partner must have the caller ID to query the API
  • Additional Data is available for 10 minutes from the first push by the data partner
  • Partners should make use of keyerror handling and utilize loops through the API response

 

Additional Reference

Refer to the RAD-E (RapidSOS Additional Data) Enhanced reference documentation for the Open API Specification, and schema details on actions for PSAP clients to access user and emergency data during an emergency. 

 

About us

We build APIs that share data with first responders to help protect lives.