Locations: the map behind every app

The three-level hierarchy

The nesting is strict and the distinctions matter more than they first appear.

The critical rule: an EVSE serves one vehicle at a time regardless of how many connectors it has. A charge point with a CCS and a CHAdeMO socket is one EVSE with two connectors, not two EVSEs. Modelling it as two is the single most common data error in the module, and it makes an app show two available bays where only one car can charge.

Why uid and evse_id are different fields

uid is the internal identifier used in every OCPI message. evse_id is the human-readable, ISO 15118 / eMI3 style identifier printed on the charger and shown to drivers. They are separate because the printed identity can change — a charger is relabelled, a site is renumbered — without the underlying object changing. Key your storage on uid and display evse_id.

Status, and what it does not tell you

EVSE status is the field drivers actually consume, whether they know it or not.

Worked example: one location, trimmed

{
  "country_code": "IN", "party_id": "EFI",
  "id": "LOC-ND-014",
  "publish": true,
  "name": "Sector 62 Hub",
  "address": "Block A, Sector 62", "city": "Noida",
  "postal_code": "201309", "country": "IND",
  "coordinates": { "latitude": "28.627400", "longitude": "77.372200" },
  "parking_type": "PARKING_LOT",
  "evses": [
    {
      "uid": "EVSE-014-02",
      "evse_id": "IN*EFI*E014002",
      "status": "AVAILABLE",
      "physical_reference": "A2",
      "connectors": [
        {
          "id": "1",
          "standard": "IEC_62196_T2_COMBO",
          "format": "CABLE",
          "power_type": "DC",
          "max_voltage": 500, "max_amperage": 125,
          "max_electric_power": 60000,
          "tariff_ids": ["TRF-DC-STD"],
          "last_updated": "2026-08-11T09:00:00Z"
        }
      ],
      "capabilities": ["REMOTE_START_STOP_CAPABLE", "RESERVABLE"],
      "last_updated": "2026-08-11T09:12:04Z"
    }
  ],
  "opening_times": { "twentyfourseven": true },
  "last_updated": "2026-08-11T09:12:04Z"
}

Three fields in there carry disproportionate weight:

• publish — false means the CPO does not want this location shown publicly. Honour it. Ignoring it is a contractual problem, not a technical one.
• tariff_ids — the join into the Tariffs module. Without it you cannot show a price, and a charging app that cannot show a price loses to one that can.
• capabilities — tells you what commands this EVSE will accept. Checking REMOTE_START_STOP_CAPABLE before offering a start button saves a guaranteed failure.

Push, pull and partial updates

Locations supports both directions, and getting the combination right is what separates an accurate map from a stale one.

• Pull (GET) with pagination, and date_from to fetch only what changed. This is your baseline sync and your repair mechanism.
• Push (PUT) replaces a whole object — a Location, an EVSE, or a Connector.
• Push (PATCH) updates individual fields. Status changes almost always arrive this way, because sending an entire Location object every time a bay frees up would be absurd.

PATCH is where implementations break. A PATCH may target a nested object directly — a specific connector inside a specific EVSE inside a location — and your handler has to apply it without disturbing sibling data. Naive implementations that fetch, merge in memory and write back will lose concurrent updates under load.

last_updated exists to protect you here: reject any update whose last_updated is older than what you already hold. Out-of-order delivery is normal, and without this check a delayed “available” can overwrite a newer “charging”.

Keeping the map honest

Availability is the most-read and least-trusted data in EV charging. What keeps it accurate:

• Never infer status from your own sessions. Your sessions are a subset — the CPO's other roaming partners and its own app are also using those chargers. The CPO's status is authoritative; yours is a guess.
• Age your data visibly. Status more than a few minutes old should be presented with a timestamp rather than as current fact.
• Full reconciliation on a schedule. Nightly full pulls catch the objects that pushes missed — and pushes always miss some.
• Handle REMOVED properly. Decommissioned EVSEs must disappear. A phantom charger sends a driver to a site where nothing exists, which is the worst possible failure for a navigation feature.
• Alert on silence, not just on errors. A CPO that has sent no location updates in 24 hours has probably broken its push integration, and you will not see an error — you will see nothing.