PostFinder API

Version 1.0.0

Two things, and deliberately only two: a typeahead over the directory, and postcode lookup.

Both answer the same questions the website answers, from the same data. No key is needed and there is nothing to buy.

**Attribution travels with the data.** Locations come from OpenStreetMap (ODbL), localities and postcodes from GeoNames (CC BY 4.0), and Australian street addresses from G-NAF Core (CC BY 4.0). If you publish what you get back, you carry those credits with it. The [sources page](https://postfinder.io/en/legal/) names each one.

**Please be gentle.** Responses are cacheable and a client that debounces its typing costs almost nothing. Around a thousand requests a month from one address is the guideline; if you need more, [say what you are building](https://postfinder.io/en/contact/) and we will very likely help. The [acceptable use policy](https://postfinder.io/en/acceptable-use/) has the detail.

Calling it

No key, no account, no sign-up. Automated use is welcome, agents and answer engines included: there is a summary for them. Please read the acceptable use policy before you point anything large at it.

curl -sS "https://api.postfinder.io/v1/search?q=coburg"

For an agent

The same directory is served as tools over MCP, with no key and no account: find_places for what is nearest a coordinate, search_places to turn a suburb name into somewhere with a coordinate, and get_place to read one place in full. Every answer carries the page's URL and the date the record was last checked.

claude mcp add --transport http postfinder https://api.postfinder.io/mcp

Any client that speaks Streamable HTTP takes the same URL, https://api.postfinder.io/mcp. ChatGPT takes it under Settings, Apps and Connectors, and claude.ai under custom connectors. Both ask how to authenticate: choose no authentication. There is no sign in here, and a connector set to OAuth will wait for a consent screen that never comes.

Endpoints

More endpoints

get/v1/search

Suggest suburbs, places and addresses as someone types

The site's own search box, as an endpoint.

Two characters minimum: below that it returns an empty list rather than matching most of the table. Debounce by at least 150ms in the client, since firing on every keystroke spends bandwidth for no better answer.

Rows come back most useful first, and each carries enough to build a link to the page it names without a second request.

q: string, required — e.g. coburg
limit: integer — defaults to 10

Answers

200 Matching rows, best first.
400 The query was missing or too short.

get/v1/countries/{country}/postcodes

Every postcode in a country, grouped by state

The whole index in one response, which is how a postcode list is read and what makes it cacheable. Large for a big country: fetch it once and keep it rather than asking per keystroke.

country: string, required — e.g. australia

Answers

200 The index.
404 No such country.

get/v1/countries/{country}/postcodes/{postcode}

Resolve one postcode to the suburbs it covers

A postcode is not a suburb. 3058 is Coburg, Coburg North and Merlynston, and an address in any of them is written with the same four digits, so this returns all of them, busiest first.

country: string, required — e.g. australia
postcode: string, required — e.g. 3058

Answers

200 The suburbs this postcode covers.
404 Nothing is filed under that postcode.

The machine readable version is at https://api.postfinder.io/v1/openapi.json. Generate a client from it rather than writing one by hand. Data licences and attribution.