postfinder
APISign in

PostFinder API

Version 1.0.0

The directory behind postfinder.io, as an API: post offices, post boxes, parcel lockers, drop off and collection points in Australia, New Zealand, the United Kingdom, the United States and Canada, and the suburbs and postcodes they sit in.

It answers 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, under the ODbL, and suburbs and postcodes from GeoNames, under 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

Nearby

What is nearest a coordinate: the question most callers are asking.

get/v1/nearby

The nearest places of one kind to a coordinate

"Where is the nearest post office": up to 30 places within 50 km, nearest first. Not cached, because every coordinate is different.

lat
number, required — e.g. -37.7404
lng
number, required — e.g. 144.9633
category
string, required — one of post-offices, post-boxes, express-post-boxes, parcel-lockers, drop-off-points, collection-points — e.g. post-offices
country
string, required — e.g. australia

Answers

  • 200 The nearest places.
  • 400 A coordinate out of range, or a missing or unknown category or country.

Search

Turn what somebody typed into a suburb or a place.

Places

The directory as the site's pages have it: countries, regions, suburbs and places.

get/v1/countries

Every country the directory covers

Each with how many regions, suburbs and locations it holds.

Answers

  • 200 The countries.
get/v1/countries/{country}

One country and its regions

The regions with a page, largest first.

country
string, required — e.g. australia

Answers

  • 200 The country.
  • 404 No such country.
get/v1/countries/{country}/regions/{region}

One region and its suburbs

A page of the region's suburbs, alphabetical, with the total for paging.

country
string, required — e.g. australia
region
string, required — e.g. victoria
limit
integer — defaults to 200
offset
integer — defaults to 0

Answers

  • 200 The region.
  • 404 No such region in that country.
get/v1/countries/{country}/categories/{category}

One kind of place across a country

"Parcel lockers in Australia": counts per region and the busiest suburbs, not a national list of every locker. A category with nothing in it answers 404 rather than an empty page.

country
string, required — e.g. australia
category
string, required — one of post-offices, post-boxes, express-post-boxes, parcel-lockers, drop-off-points, collection-points — e.g. parcel-lockers
region
string — e.g. victoria

Answers

  • 200 The category.
  • 404 No such country, or nothing of that category in it.
get/v1/localities/{country}/{region}/{locality}

One suburb: every place in it

Every open place in the suburb, with counts per category and operator and the nearest suburbs, which is the page a suburb has on the site.

country
string, required — e.g. australia
region
string, required — e.g. victoria
locality
string, required — e.g. coburg

Answers

  • 200 The suburb.
  • 404 No such suburb.
get/v1/places

Places in a suburb, filtered

Filter one suburb's places by operator or category.

The suburb is named by its numeric id, which no other endpoint returns; for most uses the suburb endpoint, which takes slugs, is the one to call.

locality
integer, required
brand
string
category
string — one of post-offices, post-boxes, express-post-boxes, parcel-lockers, drop-off-points, collection-points
limit
integer — defaults to 50

Answers

  • 200 The places, by name.
  • 400 locality is missing or not a number.
get/v1/places/{publicID}

One place in full

Everything about one place: address, opening hours, what it accepts, what is close by, and what visitors said. The id is permanent, so a stored id reads back the same place for as long as it exists.

publicID
string, required — e.g. 5puvhnr4

Answers

  • 200 The place.
  • 404 No place has that id.

Postcodes

Postcode lookup, in both directions.

get/v1/countries/{country}/postcodes

Every postcode in a country, grouped by region

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 postcodes held for that 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 Not a postcode, or nothing is filed under it.

Reference

This document.

get/v1/openapi.json

This document

The OpenAPI document for this host.

Answers

  • 200 This document.

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.