HTTPS is one of the formats available for transmitting ELS data from handset to endpoint. The HTTPS protocol is very standard, and this document won't go into detail on the protocol itself. Endpoints should receive POST messages, which will contain emergency location information in the following fields.
Note that a best effort attempt should be made to populate as many fields as
possible when the data is available, in particular, the following fields:
time, location_latitude, location_longitude and location_accuracy. ELS
messages are of little use without such data. However, in the end, every field
is considered optional. The endpoint should generally be able to handle
messages with missing/malformed fields without errors.
Endpoints should return 2XX success codes on successful reception of a message. If there is a problem with processing a message or a message must be thrown out for other reasons, endpoints should still return a 2XX success code. Different 2XX success codes may be used to track the specific handling of the message by the endpoint.
Data format is based on the latest ETSI AML specification. The following sections are most relevant:
Content
Field Specification
| Key | Value | Units | Example |
v |
Version | - | 1 |
emergency_number |
Emergency number dialed | - | 911 |
source |
Source of activation (call, sms) | - | CALL |
thunderbird_version |
Version number for thunderbird module | - | 2800 |
time |
Timestamp of beginning of call | ms (unix time) | 1438101600123 |
location_latitude |
Latitude | degrees | 37.4217845 |
location_longitude |
Longitude | degrees | -122.0847413 |
location_time |
Timestamp of location fix | ms (unix time) | 1438102600123 |
location_altitude |
Altitude (WGS84) | meters | 4 |
location_altitude_msl |
Altitude (mean sea level) | meters | 4 |
location_floor |
Floor label (as in elevator button floor label - may be non-numeric) | - | 2 |
location_source |
Location Source (gps, wifi, cell, unknown) | - | gps |
location_accuracy |
Accuracy | meters | 20 |
location_vertical_accuracy |
Vertical accuracy | meters | 2.5 |
location_vertical_accuracy_msl |
Vertical accuracy (mean sea level) | meters | 2.5 |
location_confidence |
Confidence in location accuracy | Percent (0-1) | 0.6827 |
location_bearing |
Bearing | degrees | 156.7 |
location_speed |
Speed | meters/second | 1.2 |
device_number |
Device phone number (best attempt done to format as E.164 phone number) | - | +1438101600 |
device_model |
Device model (generally of the form device manufacturer followed by the device model name) | - | Motorola Nexus 6 |
device_imsi |
IMSI | - | 310260579377451 |
device_imei |
IMEI | - | 355458061005220 |
device_iccid |
ICCID | - | 89148000001466362977 |
cell_home_mcc |
Home MCC | - | 310 |
cell_home_mnc |
Home MNC | - | 260 |
cell_network_mcc |
Network MCC | - | 310 |
cell_network_mnc |
Network MNC | - | 260 |
hmac |
Message Authentication Code | - |
Null location
Device number
The device_number field may not always be specified in some cases. ELS will
attempt to acquire the phone number from a variety of sources but it may not be
possible. We recommend: sending a SMS message in addition to an HTTPS message
and matching by IMEI and time (timestamp of beginning of call) on receiving both
to infer the device number, or working with MNOs to retrieve phone numbers using
IMEI/IMSI.
We try to format the number where possible in E.164 format with plus sign and
country dialling code prefix, followed by the subscriber number with no spaces
or brackets +1438101600. Where we are unable to infer the country code and
therefore not format the number, we will send through the original number as
provided by the source.
Altitude Elevation (Z-axis)
ELS reports z-axis location in all ELS HTTPS location messages delivered to an
ELS Endpoint. Altitude is reported in both meters above mean sea level (MSL):
location_altitude_msland meters above the WGS84 reference ellipsoid:
location_altitude (WGS is the reference World Geodetic System used by GPS).
ELS also reports vertical accuracy for both altitude measurements in meters:
location_vertical_accuracy and location_vertical_accuracy_msl. Vertical
accuracy is defined the same as location accuracy and the confidence percentile
is set by the partner. The default is set at 68% confidence. More information is
available in the Android documentation for getVerticalAccuracyMeters() and
getMslAltitudeAccuracyMeters().
With user altitude above mean sea level (MSL), it is now possible to use server-side APIs to obtain terrain altitude MSL, and thus infer user's height above ground.
Additional Emergency Information
ELS supports fields that go beyond location, collectively referred to as Additional Emergency Information (AEI). These fields are not delivered by default, and are grouped into three categories that each require explicit opt-in from the partner:
- General (device language, emergency type, information on emergency call triggers, including car crash and fall detection timestamps)
- Medical information
- Emergency contacts
Make a Configuration Change Request to enable these fields, or contact the ELS team in case of questions.
Limits & Considerations
This data may or may not be current or accurate. Medical information and emergency contacts are sourced from the emergency app on the user's device. This app is provided by the phone manufacturer, and it's up to them to decide which information they support, and whether they provide information formatted or free-form. In addition, this data is entered directly by the user. Generally this data must be sanitized.
For free-form 'string' fields, the data is passed on by ELS without modification, so there are no assurances on format nor validity. For structured fields, ELS sends their value in a certain format, but makes no assurances to the validity of this data. Examples:
- Timestamps: Assured to be a number and expected to contain a millisecond
since UNIX epoch timestamp for implementations conforming to the spec. Must
be able to gracefully handle non-valid values (e.g.
-1) for non-conforming implementations. - Dates: Assured to be in the ISO 8601
YYYY-MM-DDformat. Must be able to gracefully handle non-valid dates (e.g.2020-22-22) in case of implementations not conforming to the spec.
General
| Key | Value | Units | Example |
adr_carcrash_time |
Car Crash Timestamp | ms (unix time) | 1438101600123 |
device_languages |
BCP 47 language tags (comma separated), in order from highest priority to lowest | - | en-US,fr-FR |
emergency_type |
Type of emergency, if selected by the user during Assisted Emergency Dialing | One of MEDICAL/FIRE/POLICE | FIRE |
fall_detection_time |
Timestamp of when a fall was detected | ms (unix time) | 1438101600124 |
loss_of_pulse_time |
Timestamp of when a loss of pulse event was detected | ms (unix time) | 1438101600125 |
Emergency Contacts
| Key | Value | Units | Example |
econtact_[0-12]_name |
Name of the [0-12]th emergency contact | - | John Doe |
econtact_[0-12]_phone_number |
Phone number of the [0-12]th emergency contact | Not guaranteed to be a valid phone number | +123 456789 |
econtact_[0-12]_relationship |
User's relationship to the [0-12]th emergency contact | - | Sister |
Medical Information
| Key | Value | Units | Example |
med_info_last_updated_time |
Timestamp of when medical information was last updated | ms (unix time, not guaranteed to be valid) | 1438101600124 |
med_info_name |
Name of the user | - | Alex Smith |
med_info_date_of_birth_gregorian |
Date of birth | ISO 8601 YYYY-MM-DD (not assured to be a valid date, for example 2020-22-22) | 1990-01-03 |
med_info_date_of_birth_other |
Date of birth (free-form) | - | On the first day of year 2000 |
med_info_height |
Height | - | 180 cm |
med_info_weight |
Weight | - | 10 stones |
med_info_sex |
Biological sex (predefined) | One of UNKNOWN / MALE / FEMALE / INTERSEX / OTHER | INTERSEX |
med_info_sex_extra |
Biological sex (free form, potentially supplementary to med_info_sex) | - | Transitioning from FEMALE to MALE |
med_info_gender |
Gender | - | non-binary |
med_info_home_address |
Home Address | - | 123 Halifax Avenue, Alexandria 12345 |
med_info_blood_type_abo |
Blood type (predefined) | One of UNKNOWN / O_POSITIVE / O_NEGATIVE / O_UNKNOWN / A_POSITIVE / A_NEGATIVE / A_UNKNOWN / B_POSITIVE / B_NEGATIVE / B_UNKNOWN / AB_POSITIVE / AB_NEGATIVE / AB_UNKNOWN / H_H | B_NEGATIVE |
med_info_blood_type_other |
Blood type (free-form) | - | Le(a-b-) |
med_info_allergies |
Allergies | - | Latex |
med_info_medications |
Medications | - | Aspirin |
med_info_conditions_history |
Medical conditions history | - | Hypertension |
med_info_devices_mobility_requirements |
Medical devices or mobility requirements | - | Pacemaker |
med_info_pregnancy_status |
Pregnancy status | One of UNKNOWN / PREGNANT / NOT_PREGNANT | PREGNANT |
med_info_pregnancy_due_date |
Pregnancy due date | ISO 8601 YYYY-MM-DD (not assured to be a valid date, for example 2020-22-22) | 2022-10-10 |
med_info_pregnancy_info |
Pregnancy information | Potentially supplementary to
med_info_pregnancy_status and
med_info_pregnancy_due_date |
Planned c-section |
med_info_organ_donor |
Organ donor (predefined) | One of UNKNOWN / NO / YES | YES |
med_info_organ_donor_extra |
Organ donor (free-form) | Potentially supplementary to med_info_organ_donor |
Only heart and lungs |
med_info_advanced_directives |
Advanced directives | - | DNS |
med_info_physician_info |
Primary physician information | - | John Doe, 34 Rainbow street, +123 456789 |
med_info_other |
Other medical information | - | Privately insured, insurance ID 123-ABC-987 |
Examples
No location, with device number (E. 164 format):
v=1&thunderbird_version=220512054&emergency_number=911&source=CALL&time=1643650654147&location_latitude=%2B00.00000&location_longitude=%2B000.00000&location_time=1643650654147&location_altitude=0&location_accuracy=0&location_confidence=0&location_source=unknown&device_number=%2B1234567890&device_model=Google+Pixel+6+Pro&device_imei=123456789012345&device_imsi=234159876543210&device_iccid=12345678901234567890&cell_home_mcc=234&cell_home_mnc=15&cell_network_mcc=234&cell_network_mnc=15
No location, no device number:
v=1&thunderbird_version=220512054&emergency_number=911&source=CALL&time=1643650654147&location_latitude=%2B00.00000&location_longitude=%2B000.00000&location_time=1643650654147&location_altitude=0&location_accuracy=0&location_confidence=0&location_source=unknown&device_model=Google+Pixel+6+Pro&device_imei=123456789012345&device_imsi=234159876543210&device_iccid=12345678901234567890&cell_home_mcc=234&cell_home_mnc=15&cell_network_mcc=234&cell_network_mnc=15
Location computed, with device number (E. 164 format):
v=1&thunderbird_version=220512054&emergency_number=911&source=CALL&time=1643648829301&location_latitude=51.5332125&location_longitude=-0.1260139&location_time=1643648838875&location_altitude=77.5999985&location_altitude_msl=67.5999985&location_vertical_accuracy=0.9868233&location_vertical_accuracy_msl=0.8868233&location_accuracy=14.9460001&location_bearing=306.3276367&location_speed=0.0783991&location_confidence=0.6826895&location_source=wifi&device_number=%2B1234567890&device_model=Google+Pixel+6+Pro&device_imei=123456789012345&device_imsi=234159876543210&device_iccid=12345678901234567890&cell_home_mcc=234&cell_home_mnc=15&cell_network_mcc=234&cell_network_mnc=15
Location computed, with device number (non-E. 164 format):
v=1&thunderbird_version=220512054&emergency_number=911&source=CALL&time=1643648829301&location_latitude=51.5332125&location_longitude=-0.1260139&location_time=1643648838875&location_altitude=77.5999985&location_altitude_msl=67.5999985&location_vertical_accuracy=0.9868233&location_vertical_accuracy_msl=0.8868233&location_accuracy=14.9460001&location_bearing=306.3276367&location_speed=0.0783991&location_confidence=0.6826895&location_source=wifi&device_number=01234567890&device_model=Google+Pixel+6+Pro&device_imei=123456789012345&device_imsi=234159876543210&device_iccid=12345678901234567890&cell_home_mcc=234&cell_home_mnc=15&cell_network_mcc=234&cell_network_mnc=15
Location computed, no device number:
v=1&thunderbird_version=220512054&emergency_number=911&source=CALL&time=1643648829301&location_latitude=51.5332125&location_longitude=-0.1260139&location_time=1643648838875&location_altitude=77.5999985&location_altitude_msl=67.5999985&location_vertical_accuracy=0.9868233&location_vertical_accuracy_msl=0.8868233&location_accuracy=14.9460001&location_bearing=306.3276367&location_speed=0.0783991&location_confidence=0.6826895&location_source=wifi&device_model=Google+Pixel+6+Pro&device_imei=123456789012345&device_imsi=234159876543210&device_iccid=12345678901234567890&cell_home_mcc=234&cell_home_mnc=15&cell_network_mcc=234&cell_network_mnc=15
Location computed, with general additional emergency information:
v=1&thunderbird_version=220512054&emergency_number=911&source=CALL&time=1643648829301&location_latitude=51.5332125&location_longitude=-0.1260139&location_time=1643648838875&location_altitude=77.5999985&location_altitude_msl=67.5999985&location_vertical_accuracy=0.9868233&location_vertical_accuracy_msl=0.8868233&location_accuracy=14.9460001&location_bearing=306.3276367&location_speed=0.0783991&location_confidence=0.6826895&location_source=wifi&device_number=%2B1234567890&device_model=Google+Pixel+6+Pro&device_imei=123456789012345&device_imsi=234159876543210&device_iccid=12345678901234567890&cell_home_mcc=234&cell_home_mnc=15&cell_network_mcc=234&cell_network_mnc=15&adr_carcrash_time=1643648829100&fall_detection_time=1643648829200&loss_of_pulse_time=1643648829201&emergency_type=MEDICAL
Location computed, with medical information and emergency contacts (assuming a well-functioning emergency app providing structured data):
v=1&thunderbird_version=220512054&emergency_number=911&source=CALL&time=1643648829301&location_latitude=51.5332125&location_longitude=-0.1260139&location_time=1643648838875&location_altitude=77.5999985&location_altitude_msl=67.5999985&location_vertical_accuracy=0.9868233&location_vertical_accuracy_msl=0.8868233&location_accuracy=14.9460001&location_bearing=306.3276367&location_speed=0.0783991&location_confidence=0.6826895&location_source=wifi&device_number=%2B1234567890&device_model=Google+Pixel+6+Pro&device_imei=123456789012345&device_imsi=234159876543210&device_iccid=12345678901234567890&cell_home_mcc=234&cell_home_mnc=15&cell_network_mcc=234&cell_network_mnc=15&med_info_name=Alex+Smith&med_info_date_of_birth_gregorian=1990-01-03&med_info_height=6+ft&med_info_weight=100+kg&med_info_home_address=Test+Street+5%2C+80636+Munich&med_info_blood_type_abo=H_H&med_info_allergies=Peanuts&med_info_medications=Zestril&med_info_pregnancy_status=PREGNANT&med_info_pregnancy_due_date=2023-10-31&med_info_organ_donor=YES&med_info_other=Insurance+id%3A+12345
Location computed, with medical information and emergency contacts (assuming a well-functioning emergency app providing unstructured data and setting all possible fields):
v=1&thunderbird_version=220512054&emergency_number=911&source=CALL&time=1643648829301&location_latitude=51.5332125&location_longitude=-0.1260139&location_time=1643648838875&location_altitude=77.5999985&location_altitude_msl=67.5999985&location_vertical_accuracy=0.9868233&location_vertical_accuracy_msl=0.8868233&location_accuracy=14.9460001&location_bearing=306.3276367&location_speed=0.0783991&location_confidence=0.6826895&location_source=wifi&device_number=%2B1234567890&device_model=Google+Pixel+6+Pro&device_imei=123456789012345&device_imsi=234159876543210&device_iccid=12345678901234567890&cell_home_mcc=234&cell_home_mnc=15&cell_network_mcc=234&cell_network_mnc=15&med_info_last_updated_time=1438101600000&med_info_name=Alex+Smith&med_info_date_of_birth_other=On+the+first+day+of+year+2000&med_info_height=180+cm&med_info_weight=10+stones&med_info_sex=INTERSEX&med_info_sex_extra=Transitioning+from+FEMALE+to+MALE&med_info_gender=non-binary&med_info_home_address=123+Halifax+Avenue%2C+Alexandria+12345&med_info_blood_type_other=Le%28a-b-%29&med_info_allergies=Latex&med_info_medications=Aspirin&med_info_conditions_history=ADHD&med_info_devices_mobility_requirements=Pacemaker&med_info_pregnancy_status=PREGNANT&med_info_pregnancy_due_date=2022-10-10&med_info_pregnancy_info=Planned+c-section&med_info_organ_donor=YES&med_info_organ_donor_extra=Only+heart+and+lungs&med_info_advanced_directives=DNS&med_info_physician_info=John+Doe%2C+34+Rainbow+street%2C+%2B123+456789&med_info_other=Privately+insured%2C+insurance+ID+123-ABC-987&econtact_0_name=John+Doe&econtact_0_phone_number=000+000&econtact_0_relationship=Father&econtact_1_name=Jane+Doe&econtact_1_phone_number=111+111&econtact_1_relationship=Mother&econtact_2_name=Alice+Smith&econtact_2_phone_number=222+222&econtact_2_relationship=Sister&econtact_3_name=Bob+Smith&econtact_3_phone_number=333+333&econtact_3_relationship=Brother&econtact_4_name=Charlie+Smith&econtact_4_phone_number=444+444&econtact_4_relationship=Brother&econtact_5_name=Dan+Smith&econtact_5_phone_number=555+555&econtact_5_relationship=Cousin&econtact_6_name=Eve+Smith&econtact_6_phone_number=666+666&econtact_6_relationship=Grandmother&econtact_7_name=Mallory+Smith&econtact_7_phone_number=777+777&econtact_7_relationship=Aunt&econtact_8_name=Trent+Smith&econtact_8_phone_number=888+888&econtact_8_relationship=Uncle&econtact_9_name=Xenia+Smith&econtact_9_phone_number=999+999&econtact_9_relationship=Sister&econtact_10_name=Yara+Smith&econtact_10_phone_number=10+10+10&econtact_10_relationship=Cousin&econtact_11_name=Zane+Smith&econtact_11_phone_number=11+11+11&econtact_11_relationship=Cousin&econtact_12_name=%28truncated%29
Location computed, with medical information (assuming worst-case emergency app providing invalid, unbounded, and unstructured data):
v=1&thunderbird_version=220512054&emergency_number=911&source=CALL&time=1643648829301&location_latitude=51.5332125&location_longitude=-0.1260139&location_time=1643648838875&location_altitude=77.5999985&location_altitude_msl=67.5999985&location_vertical_accuracy=0.9868233&location_vertical_accuracy_msl=0.8868233&location_accuracy=14.9460001&location_bearing=306.3276367&location_speed=0.0783991&location_confidence=0.6826895&location_source=wifi&device_number=%2B1234567890&device_model=Google+Pixel+6+Pro&device_imei=123456789012345&device_imsi=234159876543210&device_iccid=12345678901234567890&cell_home_mcc=234&cell_home_mnc=15&cell_network_mcc=234&cell_network_mnc=15&med_info_last_updated_time=-1000&med_info_date_of_birth_gregorian=0000-00-00&med_info_sex_extra=Transitioning+from+FEMALE+to+MALE&med_info_blood_type_other=Le%28a-b-%29&med_info_pregnancy_due_date=3000-22-22&med_info_organ_donor_extra=Only+heart+and+lungs&med_info_other=Lorem+ipsum+dolor+sit+amet%2C+consetetur+sadipscing+elitr%2C+sed+diam+nonumy+eirmod+tempor+invidunt+ut+labore+et+dolore+magna+aliquyam+erat%2C+sed+diam+voluptua.+At+vero+eos+et+accusam+et+justo+duo+dolores+et+ea+rebum.+Stet+clita+kasd+gubergren%2C+no+sea+takimata+sanctus+est+Lorem+ipsum+dolor+sit+amet.+Lorem+ipsum+dolor+sit+amet%2C+consetetur+sadipscing+elitr%2C+sed+diam+nonumy+eirmod+tempor+invidunt+ut+labore+et+dolore+magna+aliquyam+erat%2C+sed+diam+voluptua.+At+vero+eos+et+accusam+et+justo+duo+dolores+et+ea+rebum.+Stet+clita+kasd+gubergren%2C+no+sea+takimata+sanctus+est+Lorem+ipsum+dolor+sit+amet.+Lorem+ipsum+dolor+sit+amet%2C+consetetur+sadipscing+elitr%2C+sed+diam+nonumy+eirmod+tempor+invidunt+ut+labore+et+dolore+magna+aliquyam+erat%2C+sed+diam+voluptua.+At+vero+eos+et+accusam+et+justo+duo+dolores+et+ea+rebum.+Stet+clita+kasd+gubergren%2C+no+sea+takimata+sanctus+est+Lorem+ipsum+dolor+sit+amet.+%0A%0ADuis+autem+vel+eum+iriure+dolor+in+hendrerit+in+vulputate+velit+esse+molestie+consequat%2C+vel+illum+dolore+eu+feugiat+nulla+facilisis+at+vero+eros+et+accumsan+et+iusto+odio+dignissim+qui+blandit+praesent+luptatum+zzril+delenit+augue+duis+dolore+te+feugait+nulla+facilisi.+Lorem+ipsum+dolor+sit+amet%2C+consectetuer+adipiscing+elit%2C+sed+diam+nonummy+nibh+euismod+tincidunt+ut+laoreet+dolore+magna+aliquam+erat+volutpat.+%0A%0AUt+wisi+enim+ad+minim+veniam%2C+quis+nostrud+exerci+tation+ullamcorper+suscipit+lobortis+nisl+ut+aliquip+ex+ea+commodo+consequat.+Duis+autem+vel+eum+iriure+dolor+in+hendrerit+in+vulputate+velit+esse+molestie+consequat%2C+vel+illum+dolore+eu+feugiat+nulla+facilisis+at+vero+eros+et+accumsan+et+iusto+odio+dignissim+qui+blandit+praesent+luptatum+zzril+delenit+augue+duis+dolore+te+feugait+nulla+facilisi.+%0A%0ANam+liber+tempor+cum+soluta+nobis+eleifend+option+congue+nihil+imperdiet+doming+id+quod+mazim+placerat+facer+possim+assum.+Lorem+ipsum+dolor+sit+amet%2C+consectetuer+adipiscing+elit%2C+sed+diam+nonummy+nibh+euismod+tincidunt+ut+laoreet+dolore+magna+aliquam+erat+volutpat.+Ut+wisi+enim+ad+minim+v%28truncated%29