Cloud API

The Cell Locator cloud API estimates device position from cellular
measurements alone — serving and neighbour cells, signal strength, and timing
advance — matched against a geo-tagged RF survey. Every successful estimate
includes an honest accuracy radius and a confidence score.

This page is the narrative guide. The API documentation can be found at Cell Locator Cloud API.

Local development can point at http://127.0.0.1:8000 when running server locally.

What the API does

1. Accepts a cellscan (CSV or JSON of one or more cells at a location, optionally a
   short time window of scans) or a single cell identity object.
2. Matches the query against the reference survey.
3. Returns latitude/longitude, accuracy_m, confidence, and method metadata.

GNSS is not required for locate. GNSS is only used when you opt into
learn mode to grow the survey.

Typical accuracy in surveyed areas is in the low hundreds of metres. Expect
lower confidence and larger errors where survey coverage is thin or absent.
See Survey Guidance.

Authentication

Register a collector once (API reference: Register a collector):

POST /api/register
Content-Type: application/json

{
  "app_version": "my-client/1.0",
  "device_label": "fleet-unit-07"
}

The response includes collector_id, a one-time token, and permissions
(default includes locate, learn, query_own, delete_own). Store the
token securely; only a hash is kept server-side.

Send it on subsequent requests:

Authorization: Bearer <token>

Optional client headers (logged with locate latency): X-App-Version,
X-App-Version-Code.

Full schemas: OpenAPI paths /api/register, /api/collectors/me, security
schemes BearerAuth and BasicAuth.

Quick start: locate

API reference: Estimate position from cell measurements

Preferred — cellscan CSV

Post the same CSV shape used by the Android app and RPi sample. Leave
latitude/longitude blank for normal locate. For a multi-scan window, put
scan age in seconds in the timestamp column (newest ≈ 0); the server
groups rows by that value.

POST /api/locate
Content-Type: application/json
Authorization: Bearer <token>

{
  "csv": "timestamp,latitude,longitude,altitude,accuracy_m,MCC,MNC,LAC/CID,TAC,CID,signal,RSRQ,TA,type,subtype,ARFCN,PCI\n0.000,,,,,234,30,,24121,2885634,-95,-8,11,LTE,LTE,1617,86\n0.000,,,,,,,,,,-102,-10,,LTE,LTE,497,390\n",
  "app_version": "my-client/1.0",
  "method": "method9"
}

Alternative — single cell

{
  "cell": {
    "mcc": 234,
    "mnc": 30,
    "tac": 24121,
    "cid": 2885634,
    "pci": 86,
    "arfcn": 1617,
    "rsrp": -95,
    "rsrq": -8,
    "ta": 11
  }
}

At least one identity field (mcc, mnc, tac, cid, pci, or arfcn)
is required.

Success response (shape)

{
  "ok": true,
  "query": [ { "mcc": 234, "mnc": 30, "tech": "LTE", "…" : "…" } ],
  "estimate": {
    "latitude": 55.951562,
    "longitude": -3.253683,
    "accuracy_m": 320.0,
    "confidence": 0.81,
    "matched_cells": 3,
    "method": "method9",
    "maps_url": "https://maps.google.com/?q=55.951562,-3.253683"
  }
}

• HTTP 200 — estimate produced (ok: true).
• HTTP 422 — no match or invalid query (ok: false, error set).
• HTTP 400 — malformed JSON.

Field-level definitions: OpenAPI operation locate (POST /api/locate).

Method selection

List ids and names with GET /methods, or see them on GET /health.

Learn mode (grow the survey)

When building coverage for your own corridors, you may submit a GNSS fix with
the cell scan so the server can append it to the reference (after computing
the estimate from the survey as-is).

Requirements:

• Authorization: Bearer <token> with the learn permission
• Body includes "learn": true and a gps object
• GNSS horizontal accuracy should be ≤ 30 m (worse fixes are skipped for
  learning)

{
  "csv": "…",
  "learn": true,
  "gps": {
    "lat": 55.951564,
    "lon": -3.253681,
    "accuracy_m": 5,
    "altitude": 111
  }
}

The locate response may then include learned: true or learn_skipped with a
reason. Learned rows default to day-only timestamps (privacy); collectors
with store_timestamps keep full timestamps.

How to survey well: Survey Guidance.

Manage your learned data:

Endpoint map

Summary:

Admin endpoints are for Melrose operations, not typical integrator clients.

Sample clients

Products and kit entitlements: Cell Locator product page.

Support

• Product / licensing: [email protected]
• Technical support: [email protected]
• Privacy (cloud service): https://cellpos.melrosenetworks.com/privacy