The South African cadastre, parcel by parcel

Overview

The Parcel Intelligence API serves the South African cadastre itself: the Erf, Farm Portion, Holding, Parent Farm, Public Place and Street parcel layers, plus survey beacons and General Plan figures export. It is the paid tier above the Plot/Coordinate API — where that product answers with a point, this one answers with the parcel: full boundary polygon, both national identifiers, region codes, sectional-scheme links, extent and survey history.

Base URL

All endpoints are versioned under /api/v1.

https://api.starlightsoftware.co.bw/api/v1/parcels

The two identifiers

Every parcel carries up to two national identifiers, and the API accepts both:

Getting Access

Access is issued under contract, per product. If your key was sold the Plot/Coordinate API only, requests here answer 403 ProductNotPermitted — adding Parcel Intelligence to an existing key is a contract change, not a new credential, so your integration keeps the key it already uses. Email info@starlightsoftware.co.bw with your business name, use case and expected volume.

Authentication

Every request carries your API key in the X-API-KEY header — the same header, and the same key, as the Plot/Coordinate API.

curl -H "X-API-KEY: YOUR_API_KEY_HERE" \
  "https://api.starlightsoftware.co.bw/api/v1/parcels/at?latitude=-31.466380&longitude=19.758913"

Keys are scoped: to products (this page requires the parcels product), to a country (Parcel Intelligence data is all South African, so a Botswana-only key is refused with CountryNotPermitted), and optionally to a term. The refusals are listed under Errors, each with a distinct error code so your integration can tell configuration problems from data problems.

Status codes

Every parcel record carries two status fields from the cadastre, each returned as an object with the raw code and a human label — never a bare letter.

Legal status (legal_status, the cadastre's LSTATUS)

Work status (work_status, the cadastre's WSTATUS)

Coverage & limitations

The dataset is per-province export: all nine provinces, across the six parcel layers, plus survey beacons and General Plan figures. Coordinates are geographic WGS84 (Hartebeesthoek94 datum). The live per-province, per-layer counts — including the export each number came from — are served by GET /coverage, which is always more current than this page.

Known gaps:

• Holding (agricultural holdings) exists in six provinces — Free State, Gauteng, KwaZulu-Natal, Limpopo, Mpumalanga and North West. The Eastern Cape, Northern Cape and Western Cape record none in the source.
• Beacons are sparse in some provinces — they are published where the offices have captured them, not as a complete national set.
• Suburb boundaries exist for only a handful of areas in the source and are not served by this API.
• Around half of Northern Cape records carry a blank work status — see Status codes for how that is handled.

Data currency

This API is loaded and is refreshed quarterly. Every response carries a dataset_version naming the export its data came from, so you always know how fresh an answer is.

Endpoints

All read-only. Lookups share one envelope: a parcels array, a message, and the dataset_version the answer came from. Paginated endpoints add next_cursor when there is more.

curl -H "X-API-KEY: YOUR_API_KEY_HERE" \
  "https://api.starlightsoftware.co.bw/api/v1/parcels/at?latitude=-31.466380&longitude=19.758913"

{
  "parcels": [
    {
      "id": 1012,
      "parcel_type": "ERF",
      "province": "NORTHERN CAPE",
      "source_key": "N065C015000200003929000001",
      "dataset_version": "csg-2026-07-18",
      "lpi": "C01500020000392900000",
      "parcel_number": 3929,
      "portion": 0,
      "tag_value": "RE/3929",
      "major_region": "CALVINIA",
      "major_code": "C0150000",
      "minor_region": "CALVINIA",
      "minor_code": "C0150002",
      "legal_status": { "code": "R", "label": "Registered" },
      "work_status": { "code": "C", "label": "Current" },
      "extent_sqm": 518.1,
      "label_point": { "latitude": -31.4663795, "longitude": 19.7589129 },
      "date_stamp": "2018-02-01"
    }
  ],
  "message": "Parcels containing this point, most specific first",
  "dataset_version": "csg-2026-07-18"
}

{
  "error": "NoParcelAtPoint",
  "message": "No parcel contains this point. The nearest parcel is included under details.nearest.",
  "details": {
    "nearest": {
      "id": 244183,
      "parcel_type": "ERF",
      "province": "NORTHERN CAPE",
      "source_key": "N064C053000500000001000000",
      "dataset_version": "csg-2026-07-18",
      "lpi": "C05300050000000100000",
      "parcel_number": 1,
      "portion": 0,
      "tag_value": "1",
      "major_region": "NAMAQUALAND",
      "major_code": "C0530000",
      "minor_region": "HONDEKLIP BAY",
      "minor_code": "C0530005",
      "legal_status": { "code": "R", "label": "Registered" },
      "work_status": { "code": "C", "label": "Current" },
      "extent_sqm": 21731924.1,
      "label_point": { "latitude": -30.3251414, "longitude": 17.2921652 },
      "date_stamp": "2025-04-07",
      "distance_meters": 420
    }
  },
  "requestId": "6b966920-4451-4ba3-a247-dbac783e9d63"
}

curl -H "X-API-KEY: YOUR_API_KEY_HERE" \
  "https://api.starlightsoftware.co.bw/api/v1/parcels/C01500020000392900000"

curl -H "X-API-KEY: YOUR_API_KEY_HERE" \
  "https://api.starlightsoftware.co.bw/api/v1/parcels/C01500020000392900000/geometry"

{
  "parcel": {
    "id": 1012,
    "parcel_type": "ERF",
    "province": "NORTHERN CAPE",
    "source_key": "N065C015000200003929000001",
    "dataset_version": "csg-2026-07-18",
    "lpi": "C01500020000392900000",
    "parcel_number": 3929,
    "…": "…"
  },
  "format": "geojson",
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [[[[19.7588904, -31.4662545], [19.7591002, -31.4662505], [19.7591052, -31.4664855], [19.7588959, -31.4664884], [19.7588904, -31.4662545]]]]
  },
  "dataset_version": "csg-2026-07-18",
  "message": "Boundary fetched successfully"
}

curl -H "X-API-KEY: YOUR_API_KEY_HERE" \
  "https://api.starlightsoftware.co.bw/api/v1/parcels/C01500020000392900000/neighbours?mode=within&distance=250"

curl -H "X-API-KEY: YOUR_API_KEY_HERE" \
  "https://api.starlightsoftware.co.bw/api/v1/parcels/search?province=NC&township=CALVINIA&parcel_number=3929"

curl -X POST -H "X-API-KEY: YOUR_API_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"points": [{"latitude": -31.466380, "longitude": 19.758913}, {"latitude": -30.323000, "longitude": 17.266000}]}' \
  "https://api.starlightsoftware.co.bw/api/v1/parcels/batch"

{
  "results": [
    {
      "id": 1012,
      "parcel_type": "ERF",
      "province": "NORTHERN CAPE",
      "source_key": "N065C015000200003929000001",
      "dataset_version": "csg-2026-07-18",
      "lpi": "C01500020000392900000",
      "parcel_number": 3929,
      "…": "…"
    },
    null
  ],
  "found": 1,
  "not_found": 1,
  "dataset_version": "csg-2026-07-18",
  "message": "Resolved 1 of 2 items"
}

Rate Limits

Your key's per-minute allowance is shared across all PlotFinder products and is agreed when the key is issued (60 requests/minute by default). Every response carries the standard headers:

RateLimit-Policy: 60;w=60
RateLimit: limit=60, remaining=57, reset=41

Exceeding it answers 429 RateLimitExceeded. A batch call counts as one request against the limit, which is what batch is for.

Errors

Errors share one JSON shape. The requestId is echoed from the X-Request-Id header (yours if you sent one) — include it when reporting a problem.

{
  "error": "ProductNotPermitted",
  "message": "This API key covers the Plot/Coordinate API only. Contact PlotFinder to add the Parcel Intelligence API.",
  "requestId": "78be60d3-4d29-4b30-a1c4-6f9f2e7f8f21"
}

Questions?

Email info@starlightsoftware.co.bw. If you are reporting a problem with a specific request, include the requestId from the response.

Request API Access