townshipamerica 1.0.2

Python SDK for the Township America PLSS and Texas TXSS coordinate conversion API

Township America Python SDK

Convert US PLSS (Public Land Survey System) and Texas TXSS legal land descriptions to GPS coordinates and back. Covers all 30 PLSS states, 37 principal meridians, and all 254 Texas counties.

Built on official BLM GCDB data — the same source used by government agencies.

Documentation · GitHub · PyPI

Installation

pip install townshipamerica

Quick Start

import os

from townshipamerica import TownshipAmerica

ta = TownshipAmerica(os.environ["TOWNSHIP_AMERICA_API_KEY"])

# Convert a PLSS description to GPS coordinates
result = ta.search("25 24N 1E 6th Meridian")
centroid = result.centroid
print(f"{centroid.geometry.latitude}, {centroid.geometry.longitude}")
# 41.077932, -104.01924

# Texas TXSS
tx = ta.search("A-175 Reeves County")
print(tx.centroid.properties.survey_system)  # TXSS

Get an API key at townshipamerica.com/api.

Examples

1. Oil & Gas: Convert Well Locations to GPS

from townshipamerica import TownshipAmerica

ta = TownshipAmerica("your_api_key")

well_locations = [
    "NE 7 102N 19W 5th Meridian",
    "SENE 22 3S 68W 6th Meridian",
    "NENE 12 4N 5E Indian Meridian",
]

# Batch convert all at once (up to 100 per request)
results = ta.batch_search(well_locations)

for fc in results:
    centroid = fc.centroid
    props = centroid.properties
    print(
        f"{props.legal_location} -> "
        f"{centroid.geometry.latitude:.6f}, {centroid.geometry.longitude:.6f} "
        f"({props.province})"
    )

2. GIS Pipeline: Reverse Geocode Field Coordinates

from townshipamerica import TownshipAmerica

ta = TownshipAmerica("your_api_key")

# GPS coordinates from a field survey
field_points = [
    (-104.086743, 41.286021),
    (-104.011880, 41.336941),
    (-104.074171, 41.336931),
]

# Batch reverse geocode to PLSS descriptions
results = ta.batch_reverse(field_points, unit="Quarter Section")

for fc in results:
    centroid = fc.centroid
    if centroid:
        print(centroid.properties.legal_location)

3. Real Estate: Look Up a Single Parcel with GeoPandas

import geopandas as gpd
from shapely.geometry import shape

from townshipamerica import TownshipAmerica

ta = TownshipAmerica("your_api_key")

result = ta.search("14 5N 3W 6th Meridian")

# Convert the grid boundary to a Shapely geometry
grid_feature = result.grid
geometry = shape(grid_feature.geometry.model_dump())

# Build a GeoDataFrame for spatial analysis
gdf = gpd.GeoDataFrame(
    [{"legal_location": grid_feature.properties.legal_location,
      "state": grid_feature.properties.province}],
    geometry=[geometry],
    crs="EPSG:4326",
)

print(gdf)
# Export to file
# gdf.to_file("parcel.geojson", driver="GeoJSON")

Async Support

import asyncio
from townshipamerica import AsyncTownshipAmerica

async def main():
    async with AsyncTownshipAmerica("your_api_key") as ta:
        result = await ta.search("25 24N 1E 6th Meridian")
        print(result.centroid.geometry.latitude)

asyncio.run(main())

API Reference

TownshipAmerica(api_key, *, base_url=..., timeout=30.0)

Method	Description
search(location)	Convert PLSS or TXSS description to GPS
reverse(longitude, latitude, *, unit=None)	Find legal description at GPS coordinates
autocomplete(query, *, limit=None, proximity=None)	Get search suggestions
batch_search(locations)	Batch convert up to 100 descriptions
batch_reverse(coordinates, *, unit=None)	Batch reverse geocode up to 100 points

All methods are also available on AsyncTownshipAmerica as async/await.

Models

• FeatureCollection — GeoJSON response with .centroid and .grid helpers
• Feature — GeoJSON Feature with .geometry and .properties
• Point, Polygon, MultiPolygon — GeoJSON geometry types

Exceptions

Exception	HTTP Status	Description
ValidationError	400	Invalid request parameters
AuthenticationError	401	Missing or invalid API key
NotFoundError	404	No results at coordinates
RateLimitError	429	Rate limit exceeded
PayloadTooLargeError	413	Batch exceeds 100 items
ServerError	5xx	Server-side error

Supported Coverage

PLSS: Alabama, Alaska, Arizona, Arkansas, California, Colorado, Florida, Idaho, Illinois, Indiana, Iowa, Kansas, Louisiana, Michigan, Minnesota, Mississippi, Missouri, Montana, Nebraska, Nevada, New Mexico, North Dakota, Ohio, Oklahoma, Oregon, South Dakota, Utah, Washington, Wisconsin, Wyoming.

Texas TXSS: All 254 counties — abstract, block/section, and survey descriptions.

License

MIT — see LICENSE for details.

MCP (AI agents)

For Claude Desktop, Cursor, and other MCP clients, use the separate python-mcp package:

pip install townshipamerica-mcp

See python-mcp for setup and tool documentation.

Links

• API Documentation
• MCP server (python-mcp)
• Get an API Key
• Township America