GovDir API

The GovDir directory as JSON: which government covers a place, which office handles each job, official links with their last check date, plain-language guides, and screening facts for a point. Free to use, no key needed to start.

API reference Changelog

Using an AI assistant such as Claude or ChatGPT? Connect it to the GovDir MCP server instead.

What it gives you

Every link comes from the directory. Each has official, publisher, verified_status and verified_at. GovDir checks links on a schedule.
The right office for each job. For a point or a place, the body that assesses, collects tax, records deeds, zones, issues permits and runs the GIS, including towns, townships and districts where the county does not.
Census identifiers. Places use prefixed GEOIDs such as county:27053 and place:2743000.
The same answer for everyone. Results and their order never depend on who asks or which tier a key is on. No office pays to appear or to rank.
The office has the final say. GovDir is a guide, not an authority. Screening facts are never an official determination.

Quickstart

Base URL https://api.govdir.com/v1. Every response is JSON with data, sources, as_of, request_id and notices.

Who handles what at a point (longitude and latitude in WGS84):

curl 'https://api.govdir.com/v1/jurisdictions/resolve?lat=44.9778&lon=-93.2650'

The same for an address, or for a place name and state:

curl 'https://api.govdir.com/v1/jurisdictions/resolve?address=350+S+5th+St,+Minneapolis,+MN'
curl 'https://api.govdir.com/v1/jurisdictions/resolve?place=Two+Harbors&state=MN'

Official resources for a topic, best first:

curl 'https://api.govdir.com/v1/resources?jurisdiction_id=county:27053&topic=parcel_map'

A place's full directory, the topic list, a guide with a state's rules, point screening and a name search:

curl 'https://api.govdir.com/v1/places/county:27053'
curl 'https://api.govdir.com/v1/topics'
curl 'https://api.govdir.com/v1/guides/assessor?state=IN'
curl 'https://api.govdir.com/v1/screening?lat=45.1&lon=-93.4'
curl 'https://api.govdir.com/v1/search?q=web+soil+survey'

County-wide parcel answers from PublicGIS, such as the biggest or most valuable parcels in a county:

curl 'https://api.govdir.com/v1/county-data?q=biggest+property+in+Aitkin+County,+MN'

The REST API has no endpoint for one property. Facts about a single parcel (parcel number, acreage, value, last sale) are available only through the MCP server tool get_property_facts.

The machine-readable description is openapi.json (OpenAPI 3.1), also at https://api.govdir.com/v1/openapi.json.

Keys

You can use the API without a key. A key raises your limits and page sizes; it never changes what a result holds or its order. Send it from your server:

curl -H 'Authorization: Bearer YOUR_KEY' 'https://api.govdir.com/v1/topics'

Keep keys off web pages. Browsers can call the API without a key from any site; the browser preflight does not allow the Authorization header.

Self-service keys are not open yet. Until then, the limits without a key apply to everyone.

Limits

Caller	Per minute	Per day
No key, per network address (an IPv6 /64 counts as one)	10	300
No key, all callers together	30	600
No key, per network address, place and resource lists	5	30
No key, all callers together, place and resource lists (also the MCP server)	10	100
Standard key	120	20,000
Partner key	600	200,000

Every response carries the IETF RateLimit-Policy and RateLimit headers, for example "minute";r=29;t=41: 29 requests left, reset in 41 seconds. Over a limit, the API answers 429 with Retry-After in seconds. Address lookups and screening also share a limit on new outside lookups.

Paging and caching

Long lists (/resources, /places/{jurisdiction_id}) take limit (1 to 100, default 50; without a key a page holds at most 50) and return next_cursor. Pass it back unchanged as cursor with the same other parameters; the Link header with rel="next" holds the same URL. next_cursor is null on the last page.
Responses carry a weak ETag. Send it back in If-None-Match to get 304 Not Modified without a body.
Cache-Control gives how long a response may be reused: a day for topics and guides, an hour for screening, 15 minutes for the rest. Errors are never cached.
Send X-Request-Id (8 to 64 letters, digits, dot, underscore or hyphen) to tag a request; it comes back as request_id.

Errors

Errors are RFC 9457 application/problem+json with type, title, status, detail and request_id. The type is stable; match on it, not on the text.

Type	Status	Meaning
`https://www.govdir.com/problems/bad-parameter`	400	A query parameter is missing, has the wrong form, or is out of range.
`https://www.govdir.com/problems/bad-point`	400	lat and lon are missing, or are not WGS84 decimal degrees.
`https://www.govdir.com/problems/bad-cursor`	400	The cursor was not issued by this endpoint for the same other parameters.
`https://www.govdir.com/problems/unknown-topic`	400, 404	The topic is not in the vocabulary at /v1/topics.
`https://www.govdir.com/problems/unknown-state`	400	The state code is not a state, DC or territory GovDir covers.
`https://www.govdir.com/problems/invalid-key`	401	The Authorization header is malformed, or the key is unknown or revoked.
`https://www.govdir.com/problems/unknown-jurisdiction`	404	No GovDir place has this jurisdiction_id.
`https://www.govdir.com/problems/outside-coverage`	404	The point is not inside a state or territory GovDir covers.
`https://www.govdir.com/problems/address-not-found`	404	No address matched.
`https://www.govdir.com/problems/place-not-found`	404	No county, city, town or township with that name in that state.
`https://www.govdir.com/problems/not-found`	404	There is no endpoint at this path.
`https://www.govdir.com/problems/method-not-allowed`	405	Only GET, HEAD and OPTIONS are answered.
`https://www.govdir.com/problems/ambiguous`	409	Several candidates match. The problem lists them in choices: resolve again with the lat and lon of an address choice, or with the jurisdiction_id of a place choice.
`https://www.govdir.com/problems/rate-limited`	429	A minute or day limit is used up. Wait the number of seconds in Retry-After.
`https://www.govdir.com/problems/lookup-limit`	429	The limit for new outside lookups (addresses and screening) is used up. Wait the number of seconds in Retry-After.
`https://www.govdir.com/problems/internal-error`	500	GovDir could not finish the request.
`https://www.govdir.com/problems/busy`	503	The same lookup is already running, or GovDir is busy. Retry after a few seconds.
`https://www.govdir.com/problems/upstream-unavailable`	503	An outside service GovDir needs, such as the address geocoder or the parcel database, did not answer.

Using the data

Say that the data comes from GovDir and link to www.govdir.com where you show it.
Show links as they come, with their verification date where you show a status. Links can break; the office named has the final say.
Keep screening labeled as screening, with its caveat.
Directory records whose source GovDir has not yet documented are left out of API answers, and a notice says how many.
Never send names of people to look up. The API does not search for people.

Versions and deprecation

This is version 1, under /v1. GovDir adds fields, topics and endpoints without notice, so ignore what you do not recognize. Nothing is removed or changed in meaning without at least 12 months' notice: the change is announced on the changelog, and the affected responses carry Deprecation and Sunset headers for the whole period. A breaking change gets a new version path.

Terms

The API Terms are being written. Until they are published, please follow the points under Using the data.

For AI agents

A short description for language models is at /llms.txt.