Cell Positioning API

Overview

The API exposes one read-only operation: given a cell_id, it returns the stored tower record (position, network identifiers, and import metadata) when a match exists. It is intended for lightweight integrations and automated lookups.

Every response follows a consistent envelope format with three fields: success (boolean), reason (string), and data (object).

Authentication

Every request must include an API key in the X-API-Key request header. The key is configured by an administrator in config.json and is never shown on this page.

X-API-Key: <your-api-key>

Replace with the key provided by your administrator. Requests with a missing or incorrect key receive a 401 response with reason: "unauthorized".

Endpoint

GET /api/v1/search

Success responses (HTTP 200)

Found

A matching record exists. success is true, reason is "cellid_found", and data holds the tower record.

{
  "success": true,
  "reason": "cellid_found",
  "data": {
    "id": 13937,
    "radio": "LTE",
    "generation": "4G",
    "mcc": 454,
    "net": 12,
    "area": 40804,
    "cell": 26099283,
    "unit": -1,
    "longitude": 113.9108,
    "latitude": 22.2953,
    "range_meters": 1000,
    "samples": 4,
    "changeable": true,
    "created_epoch": 1747783166,
    "updated_epoch": 1784349193,
    "average_signal": 0,
    "source_file": "454.csv",
    "first_imported_at": "2026-07-23T17:46:10.828039",
    "last_imported_at": "2026-07-23T17:46:10.828039"
  }
}

Not found

No record matches the given cell_id. success is false, reason is "cellid_not_found", and data is an empty object.

{
  "success": false,
  "reason": "cellid_not_found",
  "data": {}
}

Error responses

Error responses also follow the {success, reason, data} envelope. success is always false on errors.

401 Unauthorized

The X-API-Key header is missing or does not match the configured key.

{
  "success": false,
  "reason": "unauthorized",
  "data": {}
}

422 Unprocessable Entity

cell_id is missing, not an integer, or negative. The data object contains a details array describing the offending field.

{
  "success": false,
  "reason": "validation_error",
  "data": {
    "details": [
      {
        "type": "missing",
        "loc": ["query", "cell_id"],
        "msg": "Field required",
        "input": null
      }
    ]
  }
}

Examples

curl

curl -H "X-API-Key: <your-api-key>" \
  "https://your-host.example/api/v1/search?cell_id=26099283"

JavaScript (fetch)

const response = await fetch(
  "https://your-host.example/api/v1/search?cell_id=26099283",
  { headers: { "X-API-Key": "<your-api-key>" } }
);

const json = await response.json();
if (json.success) {
  console.log("Tower found:", json.data);
} else {
  console.log("Reason:", json.reason);
}