townshipamerica

Official TypeScript SDK for the Township America API — convert US PLSS (Public Land Survey System) and Texas TXSS legal land descriptions to GPS coordinates and back.

Documentation · GitHub · npm

Install

npm install townshipamerica

Quick Start

import { TownshipClient } from "townshipamerica";

const client = new TownshipClient({ apiKey: "YOUR_API_KEY" });

// PLSS to GPS
const plss = await client.search("NW 25 24N 1E 6th Meridian");
console.log(plss.latitude, plss.longitude); // 41.077932 -104.01924
console.log(plss.surveySystem); // "PLSS"

// Texas TXSS to GPS
const tx = await client.search("A-175 Reeves County");
console.log(tx.surveySystem); // "TXSS"
console.log(tx.state); // "TX"

// GPS to legal description (PLSS or TXSS depending on location)
const reverse = await client.reverse(-104.01924, 41.077932);
console.log(reverse.legalLocation);

// Autocomplete (PLSS or TXSS)
const suggestions = await client.autocomplete("A-175", { limit: 5 });
console.log(suggestions.features[0].properties.legal_location);

// Batch — mix PLSS and TXSS in one call (up to 100 per request, auto-chunks larger arrays)
const batch = await client.batchSearch([
  "NW 25 24N 1E 6th Meridian",
  "A-175 Reeves County"
]);

API Reference

new TownshipClient(options)

| Option | Type | Default | Description | | --------- | -------- | --------------------------------------- | ---------------------------------------------------------------------------------- | | apiKey | string | — | Required. Your API key from townshipamerica.com | | baseUrl | string | https://developer.townshipamerica.com | Override the API base URL | | timeout | number | 30000 | Request timeout in milliseconds |

client.search(legalLocation)

Convert a PLSS or Texas TXSS legal land description to GPS coordinates.

const plss = await client.search("NE 12 4N 5E Indian Meridian");
const tx = await client.search("A-175 Reeves County");

Returns: SearchResult

| Field | Type | Description | | ------------------------ | -------------------------- | -------------------------------------------------- | | legalLocation | string | Normalized legal description | | latitude | number | Centroid latitude | | longitude | number | Centroid longitude | | state | string | US state | | county | string | County | | unit | string \| null | PLSS unit, or null for TXSS | | surveySystem | "PLSS" \| "TXSS" | Survey system | | alternateLegalLocation | string | Alternate description format | | boundary | GeoJSONBoundary \| null | Grid boundary polygon (Polygon or MultiPolygon) | | raw | GeoJSONFeatureCollection | Raw API response |

TXSS responses also include abstract_no, block_no, survey_name, and acreage on feature properties when available.

client.reverse(longitude, latitude, options?)

Find the legal land description at GPS coordinates (PLSS or Texas TXSS).

const result = await client.reverse(-104.01924, 41.077932, {
  unit: "First Division"
});

Options:

| Option | Type | Description | | ------ | -------------------------------------------------------------- | ---------------- | | unit | 'Township' \| 'First Division' \| 'Second Division' \| 'all' | Precision filter |

Returns: SearchResult (single unit) or SearchResult[] (when unit: 'all')

client.autocomplete(query, options?)

Get autocomplete suggestions for a partial PLSS or Texas TXSS description.

const fc = await client.autocomplete("NW 25", { limit: 5 });
for (const feature of fc.features) {
  console.log(feature.properties.legal_location);
}

Options:

| Option | Type | Description | | ----------- | ------------ | ------------------------------------- | | limit | number | Max suggestions, 1–10 (default 3) | | proximity | [lng, lat] | Bias results toward these coordinates |

Returns: GeoJSONFeatureCollection

client.batchSearch(locations, options?)

Convert multiple descriptions in one request. Automatically chunks arrays larger than 100.

const results = await client.batchSearch([
  "NW 25 24N 1E 6th Meridian",
  "NE 12 4N 5E Indian Meridian"
]);
// results[0] is SearchResult or null (if no match)

Returns: (SearchResult | null)[]

client.batchReverse(coordinates, options?)

Reverse geocode multiple coordinate pairs. Automatically chunks arrays larger than 100.

const results = await client.batchReverse(
  [
    [-104.01924, 41.077932],
    [-104.648933, 41.454928]
  ],
  { unit: "Township" }
);

Options:

| Option | Type | Description | | ----------- | -------------------------------------------------------------- | ----------------------------------- | | unit | 'Township' \| 'First Division' \| 'Second Division' \| 'all' | Precision filter | | chunkSize | number | Items per request (default/max 100) |

Returns: (SearchResult | null)[]

client.boundary(legalLocation)

Get just the boundary polygon for a legal description.

const polygon = await client.boundary("NW 25 24N 1E 6th Meridian");
// polygon.type === 'Polygon'
// polygon.coordinates === [[[lng, lat], ...]]

Returns: GeoJSONPolygon | GeoJSONMultiPolygon | null

client.raw(legalLocation)

Get the raw GeoJSON FeatureCollection from the API (no transformation).

const fc = await client.raw("NW 25 24N 1E 6th Meridian");

Returns: GeoJSONFeatureCollection

Error Handling

All errors extend TownshipError:

import {
  TownshipClient,
  TownshipError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  PayloadTooLargeError
} from "townshipamerica";

try {
  await client.search("NW 25 24N 1E 6th Meridian");
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key (401)
  } else if (error instanceof NotFoundError) {
    // No results found
  } else if (error instanceof RateLimitError) {
    // Too many requests (429)
  } else if (error instanceof ValidationError) {
    // Bad request (400)
  }
}

Format Examples

PLSS (30 states)

NW 25 24N 1E 6th Meridian     → Quarter Section (First Division)
25 24N 1E 6th Meridian         → Section (Second Division)
24N 1E 6th Meridian            → Township
NE 12 4N 5E Indian Meridian   → Named meridian
7 2N 3E Black Hills Meridian  → Section with named meridian

Texas TXSS

A-175 Reeves County
Abstract 175 Reeves County Texas
Block 25 Section 14 Pecos County
Survey H&TC, Travis County

License

MIT — Maps & Apps Inc.