How to use LEI API | RapidSOS Developer Portal

Overview

The Latest Emergency Information (LEI) API provides a RESTful interface for retrieving data from the RapidSOS NG911 Clearinghouse. This API responds to GET and POST requests.

GET

/location

Gets location of the device specified by caller_id.

If no additional parameters are provided, only the most recent location record will be returned. If either start or limit is set, multiple records may be returned, as specified by param value(s).

POST

/location

Retrieves location of the device specified by caller_id.

If no additional parameters are provided, only the most recent location record will be returned. If either start or limit is set, multiple records may be returned, as specified by param value(s).

GET

/location

Location Request

You also must provide the caller_id query parameter in the URL of all GET requests. This parameter must be included in all GET requests, otherwise a 400 Bad Request response will be returned. By default, the latest stored location record for the given caller_id will be returned. Additional optional query parameters may be included to modify this behavior. These are defined below:

Query Parameters

caller_id (required) - This string (query) is a required parameter and is the phone number of the caller, numeric digits. Must always include the country code (e.g. 1 for the U.S.). For example, the number 555-555-5555 should be 15555555555
start - Not required. This integer (query) is for Start date as a UNIX timestamp (in milliseconds). If set, only records from after the start date will be returned, in ascending order. If set to a value other than a positive integer, will be ignored. The default value is 0.
limit - Not required. This integer (query) is for the number of location records to return per page. The default is 10 and the maximum is 100. If set without start, will return results starting with the oldest available record. If set to a value other than a positive integer, will be ignored.

Example request URL for latest location record:

https://api-sandbox.rapidsos.com/v1/rsos/location/?caller_id=15555555555

Note: This url structure will return the 10 most recent records by default.

Location Response

The location interface will always return a JSON response in the standard format below. If data is found, this payload will always include valid data for the location record(s) and the caller ID provided. Additionally, the information may include the name of the caller and additional information about a reverse-geocoded place closest to the location. If these resources are not available, their values in the response payload will be set to null.

Additionally, when no more records are available, making a GET request against the URL in the next field will result in a 404 Not Found response.

Note: All populated data fields will always be represented as strings, including fields for numeric values.

Example response body:

{
  "next":  "https://api-sandbox.rapidsos.com/v1/rsos/location/?caller_id=1555555555…",
  "results": [
  {
  "format_version": "1.0",
  "caller_id": "15555555555",
  "created_time": "1473983938000",
  "location_time": "1473983979750",
  "call_start_time": "1473983976778",
  "source": "call",
  "caller_name": "John Smith",
  "positioning_method": "gps",
  "latitude": "40.75371",
  "longitude":  "-73.98854",
  "altitude": "15.70227",
  "uncertainty_radius": "10.0",
  "uncertainty_confidence": "95",
  "uncertainty_confidence_pdf": "normal",
  "rg_engine": "google",
  "rg_name": "RapidSOS Inc.",
  "rg_id": "1",
  "rg_likelihood": "95",
  "rg_address": "526 7th Ave, New York, NY 10018, USA",
  "rg_exact_location": "6th floor",
  "rg_latitude": "40.75377",
  "rg_longitude": "-73.98884",
  "rg_contact": "+1 (555)-555-5555",
  "rg_additional_info_url": "https://rapidsos.com"
  }
  ]
}

See the Data Fields section of this document for a definition of the fields, as well as what fields are guaranteed to be populated and which may be null.

POST

/location

Retrieves location of the device specified by caller_id.

If no additional parameters are provided, only the most recent location record will be returned. If either start or limit is set, multiple records may be returned, as specified by param value(s).

Parameters

No parameters

Example request body

{
"query": "tel://19999999999"

}

Schema for LEIPostRequest

{

description:	Request body for LEI
called_id	string Phone number of the caller the location record belongs to. If this is the only parameter in the request, only the most recent location record will be returned.
start	integer default: :0 Start date as a UNIX timestamp (in milliseconds). If set, only records from after the start date will be returned, in ascending order. If set to a value other than a positive integer, will be ignored.
limit	integer default: 10 maximum: 100 Number of location records to return per page. The default is 10 and the maximum is 100. If set without `start`, will return results starting with the oldest available record. If set to a value other than a positive integer, will be ignored.

Location Response

The location interface will always return a JSON response in the standard format below.

Note: All populated data fields will always be represented as strings, including fields for numeric values.

Example Response Value - Success (200)

{
  "results": [
    {
      "altitude": "string",
      "application": "string",
      "call_start_time": "string",
      "caller_id": "string",
      "caller_name": "string",
      "created_time": "string",
      "format_version": "string",
      "latitude": "string",
      "location_time": "string",
      "longitude": "string",
      "positioning_method": "string",
      "rg_additional_info_url": "string",
      "rg_address": "string",
      "rg_contact": "string",
      "rg_engine": "string",
      "rg_exact_location": "string",
      "rg_id": "string",
      "rg_latitude": "string",
      "rg_likelihood": "string",
      "rg_longitude": "string",
      "rg_name": "string",
      "source": "string",
      "uncertainty_confidence": "string",
      "uncertainty_confidence_pdf": "string",
      "uncertainty_radius": "string"
    }
  ]
}

See below for a definition of the fields, as well as what fields are guaranteed to be populated and which may be null:

Data Fields

Always contains valid data

format_version- Version of the LEI format the data was rendered using
caller_id - Phone number of caller the location record belongs to
created_time - UNIX timestamp in UTC of when the location record was created
location_time - UNIX timestamp in UTC of when the location was recorded on the client device
call_start_time - UNIX timestamp in UTC of when the emergency call began
source - Trigger on the device that caused locations to be sent (Example values: "call" or "sms")
latitude - EPSG:4326 ISO6709 latitude coordinate of location record
longitude - EPSG:4326 ISO6709 longitude coordinate of location record
uncertainty_radius - EPSG:9001 circular radius of uncertainty in meters

May be set to null

caller_name - Full name of the caller
positioning_method - Technology used to obtain location e.g. "gps", "cell", "wifi"
altitude - ISO6709 altitude in meters of the location record
altitude_uncertainty_radius - vertical radius of uncertainty in meters
uncertainty_confidence - IETF RFC7459 defined value from 0-100 of the % confidence in the uncertainty radius, or null if not reported
uncertainty_confidence_pdf - IETF RFC7459 defined probability distribution function used to determine uncertainty_confidence (Possible values: "normal" or "rectangular" or "unknown")
rg_engine - Source of the reverse-geocoded address (Possible values: "google" or "apple")
rg_name - Name of the reverse-geocoded location
rg_id - Unique ID of the reverse-geocoded location specific to the rg-engine
rg_likelihood - Value from 0-100 of the % likelihood that the location record is at this place
rg_address - Civic address of the reverse-geocoded location
rg_latitude - ISO6709 latitude coordinate of the reverse-geocoded place
rg_longitude - ISO6709 longitude coordinate of the reverse-geocoded place
rg_exact_location - Additional location information e.g. floor number, apartment number, etc.
rg_contact - Contact info e.g. email or telephone number of the reverse-geocoded place
rg_additional_info_url - URL associated with reverse-geocoded place for obtaining additional data

Error Responses

In the event of an error, the location interface will return a response with one of the error status codes defined below. Additionally, the error response will always contain a JSON response body containing the detail field which will provide a more descriptive response of exactly what occurred.

Responses and Error Codes

200 Success - The request was successful
400 Bad Request - The request was missing a required or dependent query parameter
401 Unauthorized - The request was made with bad credentials
404 Not Found - No location records were found for the given caller_id
405 Method Not Allowed - The request was made with some HTTP method other than GET
429 Too Many Requests - Client has exceeded the number of allowed requests in a given time period

Example error response body:

{
"detail": "Not found."
}

Authentication Options

This interface is authenticated as described in Backend API Environments & Credential Management.

To test the interface in your browser, try it on the Reference page tab.

Additional Considerations

Review the following additional considerations when implementing Latest Emergency Information (LEI) API:

Accepts Basic Auth but will be sunset in the future, strongly recommend OAuth2.0. OAuth2.0 is required if using other egress APIs
Recommended over LIS because we receive more data + will continue to build on it
When a 911 call is made, we receive the location even if a person has their location services off
We don’t store the location information, it’s only available for ~10-20 minutes
If the location does not change, you will continue to receive the same lat/long until the data is removed from our system
For text to 911, we get 1 location payload per message
We accept VoIP for location
Not all phones can detect barometric pressure to provide a Z coordinate
We cannot provide the phone service provider, only the device software and/or communication method
We do not provide location data for landlines
Device must be iOS12+ or Android 4.0+ to provide location. Microsoft and Blackberry devices do not send location data
We do not send the call end time / time the device stopped sending locations
The partner must have the caller ID to query the API

LEI (Latest Emergency Information)1.5

Overview

GET

Location Request

Location Response

POST

Location Response

Data Fields

Error Responses

Authentication Options

Additional Considerations

About us

Contact

Documentation