Location (beta)¶

Ella Core supports three positioning methods: Cell ID, Enhanced Cell ID (E-CID), and GNSS in standalone mode. The Location API requests a subscriber's location, tracks deferred positioning sessions, and provisions the cell positions those estimates are drawn from.

Beta

The Location API is experimental and served under /api/beta. Its paths and payloads may change without notice.

Locate a Subscriber¶

This path requests a subscriber's current location. immediate returns an estimate directly; periodic and triggered open a positioning session; cancel terminates one.

Method	Path
POST	`/api/beta/location`

Parameters¶

request_type (string): immediate, periodic, triggered, or cancel.
supi (string): Subscriber identity. Required unless request_type is cancel.
method (string, optional): cell_id, ecid, or gnss. Defaults to cell_id.
mode (string, optional): network_based or ue_assisted for ecid; standalone for gnss. Defaults to every mode supported by method.
session_id (string): Session to terminate. Required when request_type is cancel.

Responses¶

Status	Condition
`200`	`immediate` request; returns a location estimate.
`201`	`periodic`/`triggered` request; returns a session `id`.
`204`	`cancel` request; no body.

Sample Response (`immediate`)¶

{
    "result": {
        "locationEstimate": {
            "shape": "POINT_UNCERTAINTY_CIRCLE",
            "point": {
                "lat": 37.7749,
                "lon": -122.4194
            },
            "uncertainty": 150
        },
        "positioningDataList": [
            {
                "method": "CELLID",
                "mode": "CONVENTIONAL",
                "usage": "SUCCESS_RESULTS_USED_TO_GENERATE_LOCATION"
            }
        ],
        "ncgi": {
            "plmnId": {
                "mcc": "001",
                "mnc": "01"
            },
            "nrCellId": "000000010"
        }
    }
}

Sample Response (`immediate`, `ecid`)¶

{
    "result": {
        "locationEstimate": {
            "shape": "POINT_UNCERTAINTY_CIRCLE",
            "point": {
                "lat": 37.7749,
                "lon": -122.4194
            },
            "uncertainty": 150
        },
        "positioningDataList": [
            {
                "method": "CELLID",
                "mode": "CONVENTIONAL",
                "usage": "SUCCESS_RESULTS_USED_TO_GENERATE_LOCATION"
            },
            {
                "method": "NR_ECID",
                "mode": "CONVENTIONAL",
                "usage": "UNSUCCESS"
            },
            {
                "method": "NR_ECID",
                "mode": "UE_ASSISTED",
                "usage": "SUCCESS_RESULTS_NOT_USED"
            }
        ],
        "ncgi": {
            "plmnId": {
                "mcc": "001",
                "mnc": "01"
            },
            "nrCellId": "000000010"
        },
        "radioMeasurements": [
            {
                "source": "UE",
                "rat": "NR",
                "serving": true,
                "pci": 180,
                "arfcn": 662592,
                "arfcnType": "SSB",
                "ssRsrp": -84,
                "ssRsrq": -11,
                "ssbBeams": [
                    {
                        "index": 0,
                        "rsrp": -84,
                        "rsrq": -11
                    }
                ]
            },
            {
                "source": "UE",
                "rat": "EUTRA",
                "serving": false,
                "pci": 148,
                "arfcn": 9310,
                "rsrp": -98,
                "rsrq": -7.5
            }
        ]
    }
}

Sample Response (`periodic`/`triggered`)¶

{
    "result": {
        "id": "018f9f3a-4c2e-7bd1-9f21-0a1b2c3d4e5f"
    }
}

List Positioning Sessions¶

This path returns the positioning sessions for a subscriber.

Method	Path
GET	`/api/beta/positioning/sessions`

Query Parameters¶

Name	In	Type	Default	Allowed	Description
`supi`	query	str			Subscriber identity. Required.

Response Fields¶

Field	Type	Description
`id`	string	Session identifier.
`supi`	string	Subscriber identity.
`session_type`	integer	`0` immediate, `1` periodic, `2` triggered.
`method`	string	Positioning method.
`status`	integer	`0` active, `1` completed, `2` failed, `3` cancelled.
`created_at`	integer	Creation time, Unix seconds.
`updated_at`	integer	Last update time, Unix seconds.

Sample Response¶

{
    "result": [
        {
            "id": "018f9f3a-4c2e-7bd1-9f21-0a1b2c3d4e5f",
            "supi": "imsi-001010000000001",
            "session_type": 1,
            "method": "ecid",
            "status": 0,
            "created_at": 1720000000,
            "updated_at": 1720000000
        }
    ]
}

Get a Positioning Session¶

This path returns a positioning session, including its most recent location estimate.

Method	Path
GET	`/api/beta/positioning/sessions/{id}`

Path Parameters¶

Name	Type	Description
`id`	string	Session identifier.

Response Fields¶

Field	Type	Description
`id`	string	Session identifier.
`supi`	string	Subscriber identity.
`session_type`	integer	`0` immediate, `1` periodic, `2` triggered.
`method`	string	Positioning method.
`status`	integer	`0` active, `1` completed, `2` failed, `3` cancelled.
`last_result`	object	Most recent location estimate.
`created_at`	integer	Creation time, Unix seconds.
`updated_at`	integer	Last update time, Unix seconds.

Sample Response¶

{
    "result": {
        "id": "018f9f3a-4c2e-7bd1-9f21-0a1b2c3d4e5f",
        "supi": "imsi-001010000000001",
        "session_type": 1,
        "method": "ecid",
        "status": 1,
        "last_result": {
            "locationEstimate": {
                "shape": "POINT_UNCERTAINTY_CIRCLE",
                "point": {
                    "lat": 37.7749,
                    "lon": -122.4194
                },
                "uncertainty": 50
            },
            "positioningDataList": [
                {
                    "method": "ECID",
                    "mode": "CONVENTIONAL",
                    "usage": "SUCCESS_RESULTS_USED_TO_GENERATE_LOCATION"
                }
            ]
        },
        "created_at": 1720000000,
        "updated_at": 1720000100
    }
}

Cancel a Positioning Session¶

This path cancels an active positioning session.

Method	Path
DELETE	`/api/beta/positioning/sessions/{id}`

Path Parameters¶

Name	Type	Description
`id`	string	Session identifier.

Returns 204 No Content on success.

List Cell Positions¶

This path returns all provisioned cell positions.

Method	Path
GET	`/api/beta/cell-positions`

Response Fields¶

Field	Type	Description
`id`	string	Cell position identifier.
`rat`	string	`nr` or `eutra`.
`mcc`	string	Mobile Country Code.
`mnc`	string	Mobile Network Code.
`cell_identity`	string	Hex cell identity (NCI for NR, ECI for E-UTRA).
`gnb_id`	string	gNB identifier.
`latitude`	number	WGS-84 latitude in decimal degrees.
`longitude`	number	WGS-84 longitude in decimal degrees.
`altitude`	number	Altitude, in metres.
`uncertainty_semi_major`	number	Semi-major axis of the uncertainty ellipse, in metres.
`uncertainty_semi_minor`	number	Semi-minor axis of the uncertainty ellipse, in metres.
`orientation_major`	integer	Orientation of the semi-major axis, in degrees.
`confidence`	integer	Confidence, in percent.
`source`	string	Origin of the record (e.g. `provisioned`).

Sample Response¶

{
    "result": [
        {
            "id": "018f9f3a-4c2e-7bd1-9f21-0a1b2c3d4e5f",
            "rat": "nr",
            "mcc": "001",
            "mnc": "01",
            "cell_identity": "000000010",
            "latitude": 37.7749,
            "longitude": -122.4194,
            "source": "provisioned"
        }
    ]
}

Create a Cell Position¶

This path provisions the geographic position of a cell antenna. Cell ID lookups resolve a subscriber's serving cell to this position.

Method	Path
POST	`/api/beta/cell-positions`

Parameters¶

rat (string): nr or eutra.
mcc (string): Mobile Country Code.
mnc (string): Mobile Network Code.
cell_identity (string): Hex cell identity (NCI for NR, ECI for E-UTRA).
gnb_id (string, optional): gNB identifier.
latitude (number): WGS-84 latitude in decimal degrees. Range -90…90.
longitude (number): WGS-84 longitude in decimal degrees. Range -180…180.
altitude (number, optional): Altitude, in metres.
uncertainty_semi_major (number, optional): Semi-major axis of the uncertainty ellipse, in metres.
uncertainty_semi_minor (number, optional): Semi-minor axis of the uncertainty ellipse, in metres.
orientation_major (integer, optional): Orientation of the semi-major axis, in degrees.
confidence (integer, optional): Confidence, in percent.

Sample Request (E-UTRA)¶

{
    "rat": "eutra",
    "mcc": "001",
    "mnc": "01",
    "cell_identity": "0000001",
    "latitude": 37.7749,
    "longitude": -122.4194
}

Sample Response¶

{
    "result": {
        "message": "Cell position created",
        "id": "018f9f3a-4c2e-7bd1-9f21-0a1b2c3d4e5f"
    }
}

Get a Cell Position¶

This path returns a provisioned cell position.

Method	Path
GET	`/api/beta/cell-positions/{id}`

Path Parameters¶

Name	Type	Description
`id`	string	Cell position identifier.

Sample Response¶

{
    "result": {
        "id": "018f9f3a-4c2e-7bd1-9f21-0a1b2c3d4e5f",
        "rat": "nr",
        "mcc": "001",
        "mnc": "01",
        "cell_identity": "000000010",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "source": "provisioned"
    }
}

Update a Cell Position¶

This path updates a provisioned cell position.

Method	Path
PUT	`/api/beta/cell-positions/{id}`

Path Parameters¶

Name	Type	Description
`id`	string	Cell position identifier.

Parameters¶

rat (string): nr or eutra.
mcc (string): Mobile Country Code.
mnc (string): Mobile Network Code.
cell_identity (string): Hex cell identity (NCI for NR, ECI for E-UTRA).
gnb_id (string, optional): gNB identifier.
latitude (number): WGS-84 latitude in decimal degrees. Range -90…90.
longitude (number): WGS-84 longitude in decimal degrees. Range -180…180.
altitude (number, optional): Altitude, in metres.
uncertainty_semi_major (number, optional): Semi-major axis of the uncertainty ellipse, in metres.
uncertainty_semi_minor (number, optional): Semi-minor axis of the uncertainty ellipse, in metres.
orientation_major (integer, optional): Orientation of the semi-major axis, in degrees.
confidence (integer, optional): Confidence, in percent.

Sample Response¶

{
    "result": {
        "message": "Cell position updated"
    }
}

Delete a Cell Position¶

This path deletes a provisioned cell position.

Method	Path
DELETE	`/api/beta/cell-positions/{id}`

Path Parameters¶

Name	Type	Description
`id`	string	Cell position identifier.

Returns 204 No Content on success.

Location (beta)¶

Locate a Subscriber¶

Parameters¶

Responses¶

Sample Response (immediate)¶

Sample Response (immediate, ecid)¶

Sample Response (periodic/triggered)¶

List Positioning Sessions¶

Query Parameters¶

Response Fields¶

Sample Response¶

Get a Positioning Session¶

Path Parameters¶

Response Fields¶

Sample Response¶

Cancel a Positioning Session¶

Path Parameters¶

List Cell Positions¶

Response Fields¶

Sample Response¶

Create a Cell Position¶

Parameters¶

Sample Request (E-UTRA)¶

Sample Response¶

Get a Cell Position¶

Path Parameters¶

Sample Response¶

Update a Cell Position¶

Path Parameters¶

Parameters¶

Sample Response¶

Delete a Cell Position¶

Path Parameters¶

Sample Response (`immediate`)¶

Sample Response (`immediate`, `ecid`)¶

Sample Response (`periodic`/`triggered`)¶