Retrieve connectivity information for an endpoint

GET

https://cdn.emnify.net/api/v1/endpoint/:endpoint_id/connectivity_info

Returns device location information based on the cell tower to which the device is connected.

emnify validates the data requested, sends the signal request to the network operator, and interprets the response. Whether the network returns useful data is outside of emnify’s control.

To distinguish these cases, this call returns the HTTP 200 OK response code whenever the request is successfully executed, even if it includes an error. See the response body for details.

Returns device location information based on the cell tower to which the device is connected. <Note> emnify validates the data requested, sends the signal request to the network operator, and interprets the response. Whether the network returns useful data is outside of emnify's control. To distinguish these cases, this call returns the HTTP `200 OK` response code whenever the request is successfully executed, even if it includes an error. See the response body for details. </Note>

Authentication

AuthorizationBearer

An auth_token should be provided to authenticate a session.

To obtain an auth_token, see the /api/v1/authenticate POST request.

Path parameters

endpoint_idintegerRequired

Numeric ID of an endpoint

Query parameters

subscriberbooleanOptionalDefaults to true

Indicates whether the subscriber information is retrieved. This parameter must be true to retrieve the connectivity information.

Upon successful execution, the response contains the following information:

success (Boolean) Indicates whether the location is successfully retrieved from the network.
state (String) Provides the subscriber state information.
- Assumed Idle - The network cannot determine whether the device is reachable.
- Network determined not reachable - Subscriber is marked not reachable by the network.
- Not provided from VLR - No information on the Visitor Location Register (VLR) exists on the core network. The following scenarios may result in this state:
  - The device is attached to a 4G/LTE-M/NB-IoT network.
  - The request for fetching location information failed.
  - The core network has no VLR information.
location (Object) Contains the following information:
- current_location_retrieved (Boolean) Indicates whether the current location is successfully retrieved.
- age_of_location (Number) Time in minutes since the last contact with the device.
- cell_global_id (Object) Includes the MCC, MNC, LAC, and CID.

Otherwise, the response contains the success field and an error (String) field with the error message.

All responses include the following fields:

request_timestamp (String, Date format) Time in UTC the location information was requested.
reply_timestamp (String, Date format) Time in UTC the network provides the location information.

Indicates whether the subscriber information is retrieved. This parameter must be true to retrieve the connectivity information. Upon successful execution, the response contains the following information: - `success` (Boolean) Indicates whether the location is successfully retrieved from the network. - `state` (String) Provides the subscriber state information. - **Assumed Idle** - The network cannot determine whether the device is reachable. - **Network determined not reachable** - Subscriber is marked not reachable by the network. - **Not provided from VLR** - No information on the Visitor Location Register (VLR) exists on the core network. The following scenarios may result in this state: - The device is attached to a 4G/LTE-M/NB-IoT network. - The request for fetching location information failed. - The core network has no VLR information. - `location` (Object) Contains the following information: - `current_location_retrieved` (Boolean) Indicates whether the current location is successfully retrieved. - `age_of_location` (Number) Time in minutes since the last contact with the device. - `cell_global_id` (Object) Includes the MCC, MNC, LAC, and CID. Otherwise, the response contains the `success` field and an `error` (String) field with the error message. All responses include the following fields: - `request_timestamp` (String, Date format) Time in UTC the location information was requested. - `reply_timestamp` (String, Date format) Time in UTC the network provides the location information.

Response

Success

Connectivity Info Success Responseobject

Connectivity Info Subscriber False Responseobject

Connectivity Info Error Responseobject

Errors

404

Not Found Error

1	{
2	"reply_timestamp": "2024-03-12T13:37:51.823Z",
3	"request_timestamp": "2024-03-12T13:37:21.415Z",
4	"subscriber_info": {
5	"location": {
6	"age_of_location": 80,
7	"cell_global_id": {
8	"cid": 1234,
9	"lac": 1234,
10	"mcc": "262",
11	"mnc": "01"
12	},
13	"current_location_retrieved": false
14	},
15	"state": "not_provided_from_vlr",
16	"success": true
17	}
18	}

$	curl -G https://cdn.emnify.net/api/v1/endpoint/12345/connectivity_info \
>	-H "Authorization: Bearer <token>" \
>	-d subscriber=true