SMS Specification

This section is divided in two parts:

1. Content - what the content of the ELS messages is.
2. Formats - how those messages are sent and how to decode them (if needed).

Content

ELS V1

ELS messages sent over SMS follow the latest ETSI AML specification. This is known as ELS V1 and it's the most common approach chosen by ELS partners. The following are the most relevant sections:

Key Name	Value	Units	Example
A"ML	Version	-	1
lt	Latitude	degrees	+37.42175
lg	Longitude	degrees	-122.08461
top	Timestamp of location	yyyyMMddHHmmss in UTC time	20150613010948
rd	Location Accuracy	meters	20.0
lc	Location Confidence	Percentage confidence	68
pm	Positioning Method (Wi-Fi, GPS, Cell, Null)	'W', 'G', 'C', 'N'	W
si	IMSI (only contains first 6 digits of original IMSI, remaining digits are replaced with 0)	-	123456000000000
ei	IMEI	-	355458061005220
mcc	Network MCC	-	310
mnc	Network MNC	-	260
ml	Length of message (including message length and header)	-	123

Positioning method

Caution: Because ELS V1 doesn't support an unknown positioning method, in rare cases ELS may return a positioning method (pm) of 'N' if the positioning method is unknown or ELS is unable to determine a location.

Null location

Caution: When ELS is unable to determine a location, per ETSI specification, it will send zero location values: lt=+00.00000,ln=+000.00000,rd=N,lc=0. See the following example for full no location behavior.

Examples

No location:

A"ML=1;lt=+00.00000;lg=+000.00000;rd=N;top=20220131173734;lc=0;pm=N;si=234159000000000;ei=123456789012345;mcc=234;mnc=15;ml=127

Location computed:

A"ML=1;lt=+51.53321;lg=-0.12601;rd=14;top=20220131171748;lc=68;pm=W;si=234159000000000;ei=123456789012345;mcc=234;mnc=15;ml=126

ELS Beta

An experimental format used by a few partners is ELS Beta, our experimental content that gives partners the opportunity to try different fields.

Warning: As this is experimental, partners should accept that there may be more regular updates to this format that may require changes to their endpoint.

The following are the most relevant sections:

Key Name	Value	Units	Example
A"ML	Version	-	2
en	Emergency Number	-	911
et	Timestamp of emergency call	UNIX epoch time in seconds (integer)	1593187189
lo	Location (latitude, longitude, accuracy) - latitude and longitude must be truncated to 5 decimal points, accuracy to 1 decimal point - an accuracy of 0 represents unknown	Degrees (float), Degrees (float), Meters (float)	37.42175,-122.08461,20.1
lt	Location time (relative to emergency time) - this field may be ignored if no location ('lo') field is present or no timestamp ('et') field is present	Seconds (integer)	5
lc	Location Confidence	Percentage confidence (integer)	68
lz	Vertical Location (altitude, vertical accuracy) - this field may be ignored if no location ('lo') field is present - all fields truncated to 1 decimal point - an accuracy of 0 represents unknown	Meters (float), Meters (float)	-10.1,10.1
ls	Location Source (Wi-fi, Cell, GPS, Fused, Unknown) - this field may be ignored if no location ('lo') field is present	'W', 'G', 'C', 'F', 'U'	W
ei	IMEI	-	355458061005220
nc	Network MCC/MNC	-	310260
hc	Home MNC/MNC	-	310260
lg	Language Tags	IETF BCP 47	en-US

Confidence level

Note: The confidence level in the message may be controlled using a configuration option. See the configuration options documentation (Partners-only access) for more information.

Altitude Elevation (Z-axis)

ELS reports vertical location and accuracy in ELS Beta messages. Altitude lz is reported in meters above the WGS84 reference ellipsoid (WGS is the reference World Geodetic System used by GPS) and accuracy in meters (altitude, vertical accuracy). This field may be ignored if no location (lo) field is present. All fields truncated to 1 decimal point and an accuracy of 0.0 represents unknown. 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().

Examples

Location not yet computed case:

A"ML=2;en=911;et=1643816841;ei=123456789012345;nc=23415;hc=23415

Location successfully computed case:

A"ML=2;en=911;et=1643816929;lo=51.53321,-0.12601,14.7;lt=6;lc=68;lz=77.6,1.0;ls=W;ei=123456789012345;nc=23415;hc=23415

Formats

ELS messages over SMS can be sent using the following formats:

• Text SMS: Regular plain SMS. This format is supported starting from Android P.
• Data SMS: The content of the message is exactly the same as Text SMS but it is encoded (more details below). This format is supported by any Android-powered device compatible with ELS.

Text SMS

Reading and parsing Text SMS is relatively straight forward. Many mobile operators offer this service and can provide you with push or pull APIs to get the content of messages sent to a standard phone number.

Note: We often refer to Text SMS as 'Hybrid SMS'. This is because when enabling Text SMS as a method of sending ELS messages, the system will switch to Data SMS for devices older than Android P.

Data SMS

Regular Text SMS format has been supported starting from Android P. Older devices will send ELS messages using Data SMS that need to be decoded. ELS Data SMS messages are encoded with the GSM 03.38 7 bit default character set and then set as the binary payload of a Data SMS.

The exact definition of a Data SMS as opposed to a normal SMS is covered later. The exact definition of the GSM 03.38 7 bit encoding can be found in 3GPP 23.038 (see section 6.1.2.1.1 specifically).

Caution: Some telephony providers may need changes to reliably transmit Data SMS messages; they differ substantially enough from 'plain text' SMS messages as to sometimes require additional configuration and monitoring.

Decode Data SMS

For the purposes of Google's usage of SMS for ELS, ELS is only concerned with SMS from the handset to the mobile service center (SMSC) - SMS-SUBMIT type messages. SMSCs should be able to receive these messages without problems as they are part of the normal SMS standard (however, in practice we have observed problems with several MNOs, ranging from infrastructure settings and policies to difficulty properly decoding Data SMS). In the following, ELS considers an SMS-SUBMIT message from the handset to the SMSC, which follows normal SMS standards (GSM 3.40). ELS defines a Data SMS as a subset of normal SMS that:

1. Has the User-Data-Header-Indicator flag set in the SMS header (6th bit of the first octet of a GSM 03.40 or 3GPP 23.040 message)
2. Contains a User-Data-Header within the User-Data of the SMS
3. The User-Data-Header contains an application port address Information-Element-Identifier (IEI)

It is necessary for ELS to send an SMS in this fashion rather than a regular SMS to ensure that ELS Data SMS messages don't appear in the Android device's messaging app. An example encoded SMS is presented later to better explain this.

Note that we don't specify a particular Data-Coding-Scheme (DCS) here. The DCS is used to identify the encoding within the User-Data segment. However, for the foreseeable future, the Data-Coding-Scheme will always be set to 8 bit data to allow for maximum flexibility, and the actual data itself will be encoded with the GSM 03.38 7 bit default alphabet. Each 7 bit encoded element will thus occupy only 7 bits, not 8 bits.

Given that the User-Data segment has a maximum of 140 bytes, and that the minimum size of a User-Data-Header that includes port information is 7 bytes, this leaves a maximum of 133 bytes (152 7 bit encoded elements) to encode the actual emergency message. These bytes may be decoded to reveal the ELS Data SMS message being transmitted.

Caution: many SMS communications providers (companies such as Twilio, Nexmo, etc...) may need additional configuration to decode this raw binary data as they often assume UTF8 encoding. If such a provider is used, it may be necessary to communicate that you need access to the raw binary data.

Example

Thus, after decoding this example Data SMS, we're left with the binary user Data of this hex string:

415193D98BEDD8F4DEECE6A2C962B7DA8E7DEEB56232990B86A3D9623B39B92783EDE86F784F068BD560B6D80C1683E568B81D7BDCB3E176F076EFB89BA77B39DCCD56A3C966B15D39DD9BD570B2590E56CBC168B21A4DB66B8FC7BD590CB66BBBC73D990DB66BB37B31D94CC12CBBCF74B40E1493CD1A

Decode GSM 03.38

The following example decodes the first couple octets, the rest is left as an exercise to the reader. We suggest referencing 3GPP 23.038 and using many of the helpful online tools (for example, http://smstools3.kekekasvi.com/topic.php?id=288). Within the Octets column, the yellow highlighted sections represent the bits that are not used for the current septet, and are left over for the next septet. Within the Septets column, the yellow highlighted sections represent the bits from the previous octet.

Hex	Octets	Septets	Character (Hex)
41	01000001	1000001	A (41)
51	01010001	0100010	" (22)
93	10010011	1001101	M (4D)
D9	11011001	1001100	L (4C)
8B	10001011	0111101	= (3D)
ED	11101101	0110001	1 (31)
D8	11011000	0111011	; (3B)
		1101100	l (6C)
F4	11110100	1110100	t (74)
DE	11011110	0111101	= (3D)

The end result here is that the previous message may be decoded into the following string:

A"ML=1;lt=37.42175;lg=-122.08461;rd=20;top=20150613010948;lc=68;pm=G;si=987654231;ei=358239059042542;mcc=310;mnc=260;ml=123

These SMS should be able to be decoded with most publicly available SMS software.