By Township Canada
Geocode Legal Land Descriptions in a Government GIS Pipeline with the Batch API
Send DLS, LSD, and NTS descriptions from an ETL job to the Township Canada Batch API and get GeoJSON parcel boundaries and centroids back.
Many public land records are keyed by legal land description, not by coordinates. A permit register, a disposition table, or a list of inspected sites can hold NW-14-32-21-W4 or 10-36-42-3-W5 in a text column and nothing else about location. That works for the people who read the records. However, it does not work for the dashboard, the map service, or the spatial join that the GIS team runs every night, because those tools need geometry.
Teams usually close that gap in one of two ways. Someone exports the records, converts them in a separate tool, and imports the coordinates again, which breaks the link between the source table and the map on every refresh. Or someone writes a parser, which works until it meets a different meridian, an LSD written with a prefix, a BC NTS reference, or a river lot. The Township Canada Batch API takes a third route: the pipeline sends the descriptions it already has and gets GeoJSON back as one step of the normal job.
What the Batch API takes and returns
The endpoint is POST https://developer.townshipcanada.com/batch/legal-location. The request body is a JSON array of legal land descriptions, up to 100 per request, and the API key goes in the X-API-Key header:
curl -X POST https://developer.townshipcanada.com/batch/legal-location \
-H "X-API-Key: $TOWNSHIP_CANADA_API_KEY" \
-H "Content-Type: application/json" \
-d '["NW-14-32-21-W4", "10-36-42-3-W5", "SE-22-40-14-W3"]'
The same array can mix DLS townships, sections, quarter sections, and LSDs with NTS references, river lots, and Ontario lots and concessions. You don't need to sort records by survey system before you send them.
The response is a JSON array with one GeoJSON FeatureCollection for each description that matched. Each collection holds two features: the parcel boundary ("shape": "grid") and its centre point ("shape": "centroid"). Both carry the same properties:
{
"type": "Feature",
"geometry": { "type": "Point", "coordinates": [-112.880937, 51.747298] },
"properties": {
"shape": "centroid",
"search_term": "NW-14-32-21-W4",
"legal_location": "NW-14-32-21-W4",
"unit": "Quarter Section",
"survey_system": "DLS",
"province": "Alberta"
}
}
search_term is the description you sent, and legal_location is the parcel it resolved to. Coordinates are WGS84 longitude and latitude, the GeoJSON default. A description that does not match a parcel gets no collection in the response. Therefore, join results back to your records on search_term, and treat any input without a match as a row to review.
There is a reverse endpoint, POST /batch/coordinates, for the opposite direction. The Batch API guide covers both endpoints and their status codes.
Drop the call into an existing ETL job
The API does not page results or split large inputs for you. Instead, your job sends the records in chunks of 100. The Python sketch below reads a list of descriptions, cleans it, sends it in chunks, and keeps every returned feature:
import os
import time
import requests
API_URL = "https://developer.townshipcanada.com/batch/legal-location"
HEADERS = {"X-API-Key": os.environ["TOWNSHIP_CANADA_API_KEY"]}
CHUNK_SIZE = 100
def geocode(descriptions):
# One empty or non-text value rejects the whole request, so drop them first.
clean = sorted({d.strip() for d in descriptions if isinstance(d, str) and d.strip()})
features = []
for start in range(0, len(clean), CHUNK_SIZE):
chunk = clean[start : start + CHUNK_SIZE]
for attempt in range(3):
resp = requests.post(API_URL, json=chunk, headers=HEADERS, timeout=60)
if resp.status_code != 429:
break
time.sleep(2 ** attempt)
resp.raise_for_status()
for collection in resp.json():
features.extend(collection["features"])
time.sleep(1) # Build tier: one request per second
return clean, features
descriptions = ["NW-14-32-21-W4", "10-36-42-3-W5", "SE-22-40-14-W3"]
sent, features = geocode(descriptions)
centroids = {f["properties"]["search_term"]: f for f in features if f["properties"]["shape"] == "centroid"}
unmatched = [d for d in sent if d not in centroids]
Three details in this sketch matter in production. First, duplicates are removed before sending, because a register often lists the same quarter section many times and each record counts against your quota. Second, the job waits between requests and retries when the API returns 429. A 429 can also mean the monthly quota is used up, and retrying will not fix that. Third, unmatched is kept as its own list, so a wrong meridian or a transposed township shows up in a report instead of disappearing from the map.
If your pipeline is in Python, the townshipcanada package on PyPI wraps the same endpoint. Its batch_search method splits lists longer than 100 into chunks for you.
Plan the volume
The Batch API is its own subscription, separate from the Search API. Quotas count requests, and each request can carry up to 100 descriptions:
| Tier | Price | Requests per month | Rate limit |
|---|---|---|---|
| Build | $40/month | 1,000 | 1 request/second |
| Scale | $200/month | 10,000 | 5 requests/second |
| Enterprise | $1,000/month | 100,000 | Higher |
With full chunks, a Build key covers up to 100,000 descriptions a month. A nightly job that sends only new or changed records uses far less than that. A one-time backfill of a large register finishes faster on Scale, which allows five requests a second. Current prices and tiers are on the API page.
Use the GeoJSON where you already work
Write the boundary features to a GeoJSON file, which QGIS, ArcGIS Pro, and PostGIS can all read:
import json
boundaries = [f for f in features if f["properties"]["shape"] == "grid"]
with open("records.geojson", "w") as fh:
json.dump({"type": "FeatureCollection", "features": boundaries}, fh)
QGIS opens a .geojson file directly as a vector layer. In ArcGIS Pro, the JSON To Features tool converts it to a feature class. For desk lookups inside ArcGIS Pro, the ArcGIS Pro locator runs on the Township Canada API too. In a database, PostGIS reads each geometry with ST_GeomFromGeoJSON, so you can load the centroids and boundaries next to the source table and join them on search_term. If the records already live in Snowflake, the Snowflake external function guide shows how to call the Batch API from SQL without leaving the warehouse.
Keys and environments
Keep the API key in an environment variable or your platform's secret store, not in the job's source code. The sketch above reads it from TOWNSHIP_CANADA_API_KEY.
Each Township Canada API key is its own subscription, with its own tier and monthly quota. This means a test run in a staging pipeline cannot use up the production job's requests if each environment has its own key. It also means you can size each key to its job: a Build key for nightly updates, and a Scale key for the backfill that runs once.