location_retrieval

The location_retrieval command obtains the current estimated geographic area of a mobile device directly from mobile network infrastructure. It returns the geographic boundary (center point and radius) within which the device is currently registered on the mobile network.

Because the location is resolved through core network signaling and radio cell coverage rather than device-side GPS, the service requires no client application on the handset and operates independently of satellite visibility or mobile operating system permissions. This makes location_retrieval a vital capability for roadside assistance, emergency services, logistics tracking, and lone-worker safety where destination coordinates are not known in advance.

Request Reference

To invoke location_retrieval, include the command in the commands array alongside the target phone number. Geographical coordinates are not required in the request.

number: Phone number in ITU E.164 format with leading +. Required.
max_age: Optional integer (in seconds) supplied inside the location_area object, specifying the maximum acceptable age of the network location fix. Where omitted, the operator applies its own default. When specified, the minimum accepted value is 60 seconds.

The radius returned in the response represents the cellular network cell resolution, not a margin of error around an exact coordinate. Urban macro-cells typically yield narrower radii than rural cells.

Access requires explicit authorization. Handling of authorization and lookup outcomes:

Partial Authorization: When querying multiple commands and location_retrieval is unauthorized for your API key, the device_location block is omitted from the response and the command is not billed.
Command-Level Failure: If multiple commands fail or are unauthorized, the service returns Status 2 with a composite status message detailing the affected commands.
Single Command Failure: If location_retrieval is the only command requested and the device cannot be located on the network, the service returns Status 2.

Response Reference

Field Name	Data Type	Output Values	Description
device_location	JSON Block	{location data}, Omitted	Primary container block for the device's retrieved geographic area. Omitted if the command was not requested, unauthorized, or the device could not be located.
area_type	String	CIRCLE, Omitted	Geometric shape representing the network coverage area. CIRCLE: The estimated area is defined by a circular boundary centered at a specific geographic point with an associated radius.
latitude	Number	Decimal degrees, Omitted	Latitude of the center point of the circular area, between -90.0 and 90.0.
longitude	Number	Decimal degrees, Omitted	Longitude of the center point of the circular area, between -180.0 and 180.0.
radius	Number	Meters, Omitted	Radius of the coverage area expressed in meters. Represents the area boundary committed by the cellular network cell. A larger radius indicates a broader cell coverage area.
last_location_time	String	ISO 8601 UTC timestamp, Omitted	Date and time when the device's network location fix was recorded by the mobile operator.

Summary Table

Command	Description	Response Values
`location_retrieval`	Retrieves the current estimated circular area of a mobile device directly from MNO cellular network infrastructure.	area_type: CIRCLE latitude: Decimal degrees of the center point longitude: Decimal degrees of the center point radius: Radius in meters last_location_time: ISO 8601 UTC timestamp

API reference

Request

curl -X POST "https://api.connect.plumma.it/services/api" \
  -H "Content-Type: application/json" \
  -H "x-plumma-connect-api-key: YOUR_API_KEY_HERE" \
-H "x-plumma-connect-app-id: YOUR_APP_ID_HERE" \
  -d '{
  "number": "+541122358032",
  "commands": [
    "location_retrieval"
  ],
  "location_area": {
    "max_age": 60
  }
}'

Response (device located)

{
  "number": "+541122358032",
  "status": 0,
  "status_message": "Response from one supplier - This response is for demo purpose only [cmd_enc=4194304] [{location_retrieval=SUPPLIER0 : Success}]",
  "device_location": {
    "area_type": "CIRCLE",
    "latitude": -34.570518,
    "longitude": -58.396377,
    "radius": 2000.0,
    "last_location_time": "2025-10-31T17:38:44.000Z"
  },
  "version": "1.0.2-20260608095239"
}

Response (device not found)

{
  "number": "+541100000000",
  "status": 2,
  "status_message": "The specified resource is not found [cmd_enc=4194304] [{location_retrieval=SUPPLIER0 : Not Found}]",
  "version": "1.0.2-20260608095239"
}

Read this in the portal, with search and the reference beside it: Location Retrieval