By Township Canada
Adding Legal Land Description Autocomplete to a Web App
How the Township Canada Autocomplete API works in a type-ahead field: request, response, survey system filtering, map hand-off, and plan fit.
A field tool, a farmland evaluation app, or an internal GIS portal eventually needs a box where people type a legal land description. Without help, the user types the whole string, NW-25-24-1-W5, submits it, and finds out afterwards that the range was wrong or the meridian was missing. A type-ahead field fixes that at the point of entry: the user types NW-25-24, sees real descriptions that exist on the survey grid, and picks one.
The Township Canada Autocomplete API is built for that field. This post covers when to use it, what the endpoint takes and returns, how to filter and hand results to a map, and how to size a plan for it. The autocomplete guide has the complete vanilla JS and React components; here the focus is on the design decisions around them.
Autocomplete or a direct lookup
The two endpoints answer different questions. The Search API takes a complete description and returns its boundary and centre point. The Autocomplete API takes a partial description and returns up to ten real descriptions that match it, each with a centre point.
If your users paste descriptions from documents, a single search call on submit is enough. If they type descriptions by hand, especially on a phone in the field, autocomplete catches mistakes before they become a wrong location. Many apps use both: autocomplete while typing, then a search call for the description the user picks.
The endpoint
GET https://developer.townshipcanada.com/autocomplete/legal-location
X-API-Key: YOUR_API_KEY
| Parameter | Required | Description |
|---|---|---|
location | Yes | The partial description typed so far, e.g. NW-2 |
limit | No | Number of suggestions, 1 to 10 (default 3) |
proximity | No | A point as lng,lat; nearer suggestions rank first |
The response is a GeoJSON FeatureCollection. Each feature is a centre point, and its properties carry what you need to render a suggestion:
{
"type": "Feature",
"geometry": { "type": "Point", "coordinates": [-114.01924, 51.077932] },
"properties": {
"shape": "centroid",
"search_term": "NW-25-24-1",
"legal_location": "NW-25-24-1-W5",
"unit": "Quarter Section",
"survey_system": "DLS",
"province": "Alberta"
}
}
An empty features array is a normal answer: nothing matches yet. A 400 means a bad limit or proximity value, and a 429 means the key hit its rate limit or monthly quota.
A minimal integration
Two habits keep the field fast and the request count sensible. Wait for a short pause in typing before calling the API, and cancel any request that a newer keystroke has made stale. Keep the key on your server, too: a key in browser code can be copied by anyone who opens the developer tools. A small route on your backend that forwards the query is enough.
// Server: forward the query and keep the key out of the browser
export async function suggest(location, proximity) {
const params = new URLSearchParams({ location, limit: "5" });
if (proximity) params.set("proximity", proximity);
const res = await fetch(
`https://developer.townshipcanada.com/autocomplete/legal-location?${params}`,
{
headers: { "X-API-Key": process.env.TOWNSHIP_CANADA_API_KEY }
}
);
if (!res.ok) throw new Error(`Autocomplete failed: ${res.status}`);
return res.json();
}
// Browser: debounce, cancel stale requests, render labels
let timer;
let controller;
input.addEventListener("input", () => {
clearTimeout(timer);
const query = input.value.trim();
if (query.length < 2) return;
timer = setTimeout(async () => {
controller?.abort();
controller = new AbortController();
try {
const res = await fetch(`/api/lld-suggest?location=${encodeURIComponent(query)}`, {
signal: controller.signal
});
const { features } = await res.json();
render(features.map((f) => f.properties.legal_location));
} catch (err) {
if (err.name !== "AbortError") console.error(err);
}
}, 300);
});
If your app shows a map, pass its centre as proximity. A short query like NW-2 matches descriptions all over the prairies, and proximity puts the ones near the user's view first.
Filtering by survey system
The endpoint searches every system it knows at once: DLS (including LSDs), BC's NTS grid, Manitoba river lots, and Ontario geographic townships. There is no parameter to restrict it. Instead, every suggestion is tagged in properties.survey_system with one of DLS, NTS, River Lot, or Geographic Township, so you can filter in your own code.
Because limit applies before your filter, ask for more than you plan to show. An Alberta-only well tool might request limit=10, keep the DLS suggestions, and display the first five. The province property allows the same trick when your app covers one province.
Handing a suggestion to the map
Each suggestion already has a centre point, which is enough to fly the map to it. When you also want the outline, call the Search API with the chosen legal_location. It returns the boundary polygon and the centre point together, so you can draw the quarter section or LSD and fit the map to it. The API documentation lists both endpoints side by side.
Rate limits and plan fit
Autocomplete and Search are separate API products, each with its own subscription on the same three tiers:
| Tier | Price | Requests per month | Rate limit |
|---|---|---|---|
| Build | $20/month | 1,000 | 1/sec |
| Scale | $100/month | 10,000 | 5/sec |
| Enterprise | $500/month | 100,000 | 25/sec |
Annual billing is ten times the monthly price. Every debounced call counts as one request, so the number to estimate is pauses per lookup, not lookups. A user who pauses three times while typing a description spends three autocomplete requests and then one search request. Measure that ratio on your own users before picking a tier. When a key reaches its monthly quota, requests return 429 until the next month or a tier change.
Autocomplete fits interactive traffic: one person, one field, a few requests per lookup. When the input is a list, such as a spreadsheet of wells or a lease schedule, use the batch endpoint instead, which converts up to 100 descriptions per request. Prices for all three products are on the API page.