API Usage Guide

The PLSS Lookup Tool exposes a REST API that you can call from any language or tool. All endpoints accept and return JSON. The base URL is wherever your server is running (default: http://localhost:3000).

1 Quick Start

Look up a PLSS section and get back its centroid coordinates:

import requests

resp = requests.post("http://localhost:3000/api/lookup", json={
    "state": "SD",
    "township": 118,
    "townshipDir": "N",
    "range": 59,
    "rangeDir": "W",
    "section": 32,
})

data = resp.json()
print(data["centroid"])  # {"lat": 44.986479, "lon": -97.953311}
print(data["label"])     # "T118N R59W, Sec 32, 5th Principal Meridian, SD"

2 Endpoints

POST /api/lookup

Look up a PLSS location by structured fields or a freeform description string. Returns GeoJSON geometry, centroid, PLSSID, and parsed components.

Structured Request Body

Parameter	Type	Required	Description
state	string	Yes	Two-letter state abbreviation (e.g. "SD", "ND")
township	integer	Yes	Township number (1-200)
townshipDir	string	Yes	"N" or "S"
range	integer	Yes	Range number (1-200)
rangeDir	string	Yes	"E" or "W"
section	integer	No	Section number (1-36). Omit to get the full township.
meridian	string	No	Meridian code (e.g. "05"). Auto-detected if omitted.

Freeform Request Body

Parameter	Type	Required	Description
state	string	Yes	Two-letter state abbreviation
description	string	Yes	Freeform PLSS description (e.g. "T117N R65W Sec 26, 5th PM")
meridian	string	No	Meridian code override

Response

{
  "parsed": {
    "township": 118,
    "townshipDir": "N",
    "range": 59,
    "rangeDir": "W",
    "section": 32,
    "meridian": "05",
    "meridianName": "5th Principal"
  },
  "plssid": "SD051180N0590W0",
  "centroid": {
    "lat": 44.986479,
    "lon": -97.953311
  },
  "label": "T118N R59W, Sec 32, 5th Principal Meridian, SD",
  "geojson": { /* GeoJSON FeatureCollection */ }
}

POST /api/reverse

Reverse geocode a lat/lon coordinate to find which PLSS section it falls within.

Request Body

Parameter	Type	Required	Description
lat	number	Yes	Latitude (-90 to 90)
lon	number	Yes	Longitude (-180 to 180)

Response

{
  "description": "T118N R59W, Sec 32, 5th Principal Meridian, SD",
  "parsed": {
    "township": 118,
    "townshipDir": "N",
    "range": 59,
    "rangeDir": "W",
    "section": 32,
    "meridian": "05",
    "meridianName": "5th Principal",
    "state": "SD"
  },
  "plssid": "SD051180N0590W0",
  "centroid": {
    "lat": 44.986479,
    "lon": -97.953311
  },
  "geojson": { /* GeoJSON FeatureCollection */ }
}

GET /api/states

Returns the list of all PLSS states with their abbreviations.

Response

[
  { "name": "Alabama", "abbr": "AL" },
  { "name": "Alaska", "abbr": "AK" },
  // ...
]

GET /api/meridians?state={abbr}

Returns available meridians for a given state.

Response

[
  { "name": "5th Principal", "code": "05" }
]

GET /api/counties?state={abbr}

Returns county names for a given state.

Response

["Aurora", "Beadle", "Bennett", /* ... */]

3 Examples

Python — Batch lookup with centroids

import requests

BASE = "http://localhost:3000"

sections = [
    {
        "state": "SD",
        "township": 118,
        "townshipDir": "N",
        "range": 59,
        "rangeDir": "W",
        "section": 32,
    },
    {
        "state": "ND",
        "township": 140,
        "townshipDir": "N",
        "range": 98,
        "rangeDir": "W",
        "section": 5,
    },
]

for sec in sections:
    resp = requests.post(f"{BASE}/api/lookup", json=sec)
    data = resp.json()
    c = data["centroid"]
    print(f"{data['label']}  ->  {c['lat']}, {c['lon']}")

Python — Freeform description lookup

resp = requests.post("http://localhost:3000/api/lookup", json={
    "state": "SD",
    "description": "T117N R65W Sec 26, 5th PM",
})
data = resp.json()
print(data["centroid"])

cURL — Reverse lookup

curl -X POST http://localhost:3000/api/reverse \
  -H "Content-Type: application/json" \
  -d '{"lat": 44.986, "lon": -97.953}'

4 Error Handling

Errors return a JSON object with an error field and an appropriate HTTP status code.

Status	Meaning	Example
400	Invalid or missing parameters	"township must be an integer between 1 and 200"
404	No results found	"No results found for the given PLSS description"
500	Internal server error	"Internal server error"