Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: PostFinder Places API
version: 1.0.0
description: '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.'
contact:
name: PostFinder
url: https://postfinder.io/en/contact/
servers:
- url: https://api.postfinder.io
description: Production
security: []
tags:
- name: Places
description: 'The directory as the site''s pages have it: countries, regions, suburbs and places.'
paths:
/v1/countries:
get:
tags:
- Places
operationId: countries
summary: Every country the directory covers
description: Each with how many regions, suburbs and locations it holds.
parameters: []
responses:
'200':
description: The countries.
content:
application/json:
schema:
$ref: '#/components/schemas/CountriesResponse'
/v1/countries/{country}:
get:
tags:
- Places
operationId: country
summary: One country and its regions
description: The regions with a page, largest first.
parameters:
- name: country
in: path
required: true
description: 'Country slug as the site''s URLs use it: australia, new-zealand, united-kingdom, united-states, canada.'
example: australia
schema:
type: string
responses:
'200':
description: The country.
content:
application/json:
schema:
$ref: '#/components/schemas/CountryResponse'
'404':
description: No such country.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/countries/{country}/regions/{region}:
get:
tags:
- Places
operationId: region
summary: One region and its suburbs
description: A page of the region's suburbs, alphabetical, with the total for paging.
parameters:
- name: country
in: path
required: true
description: 'Country slug as the site''s URLs use it: australia, new-zealand, united-kingdom, united-states, canada.'
example: australia
schema:
type: string
- name: region
in: path
required: true
description: Region slug.
example: victoria
schema:
type: string
- name: limit
in: query
required: false
description: How many suburbs. Outside 1 to 500, the default applies.
schema:
type: integer
minimum: 1
maximum: 500
default: 200
- name: offset
in: query
required: false
description: How many to skip, for the next page.
schema:
type: integer
minimum: 0
default: 0
responses:
'200':
description: The region.
content:
application/json:
schema:
$ref: '#/components/schemas/RegionResponse'
'404':
description: No such region in that country.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/countries/{country}/categories/{category}:
get:
tags:
- Places
operationId: category
summary: One kind of place across a country
description: '"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.'
parameters:
- name: country
in: path
required: true
description: 'Country slug as the site''s URLs use it: australia, new-zealand, united-kingdom, united-states, canada.'
example: australia
schema:
type: string
- name: category
in: path
required: true
description: The kind of place.
example: parcel-lockers
schema:
type: string
enum:
- post-offices
- post-boxes
- express-post-boxes
- parcel-lockers
- drop-off-points
- collection-points
- name: region
in: query
required: false
description: A region slug, to narrow the counts and the busiest suburbs to one region.
schema:
type: string
example: victoria
responses:
'200':
description: The category.
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryResponse'
'404':
description: No such country, or nothing of that category in it.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/localities/{country}/{region}/{locality}:
get:
tags:
- Places
operationId: locality
summary: 'One suburb: every place in it'
description: 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.
parameters:
- name: country
in: path
required: true
description: 'Country slug as the site''s URLs use it: australia, new-zealand, united-kingdom, united-states, canada.'
example: australia
schema:
type: string
- name: region
in: path
required: true
description: Region slug.
example: victoria
schema:
type: string
- name: locality
in: path
required: true
description: Suburb slug.
example: coburg
schema:
type: string
responses:
'200':
description: The suburb.
content:
application/json:
schema:
$ref: '#/components/schemas/LocalityResponse'
'404':
description: No such suburb.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/places:
get:
tags:
- Places
operationId: places
summary: Places in a suburb, filtered
description: '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.'
parameters:
- name: locality
in: query
required: true
description: The suburb's numeric id.
schema:
type: integer
- name: brand
in: query
required: false
description: 'An operator key: auspost.'
schema:
type: string
- name: category
in: query
required: false
description: A kind of place.
schema:
type: string
enum:
- post-offices
- post-boxes
- express-post-boxes
- parcel-lockers
- drop-off-points
- collection-points
- name: limit
in: query
required: false
description: How many places. Outside 1 to 200, the default applies.
schema:
type: integer
minimum: 1
maximum: 200
default: 50
responses:
'200':
description: The places, by name.
content:
application/json:
schema:
$ref: '#/components/schemas/PlacesResponse'
'400':
description: locality is missing or not a number.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/places/{publicID}:
get:
tags:
- Places
operationId: place
summary: One place in full
description: '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.'
parameters:
- name: publicID
in: path
required: true
description: The place's permanent id, the last segment of its URL.
example: 5puvhnr4
schema:
type: string
pattern: ^[a-z2-7]{8}$
responses:
'200':
description: The place.
content:
application/json:
schema:
$ref: '#/components/schemas/PlaceResponse'
'404':
description: No place has that id.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
schemas:
Review:
type: object
description: One approved review.
properties:
id:
type: integer
description: Review id.
name:
type: string
description: The name the reviewer chose.
outcome:
type: string
description: How the visit went.
enum:
- as_listed
- different
- no_go
rating:
type:
- integer
- 'null'
description: One to five, or null when not rated.
minimum: 1
maximum: 5
body:
type: string
description: What they wrote, when they wrote anything.
created_at:
type: string
description: When it was written.
format: date-time
required:
- id
- name
- outcome
- rating
- created_at
additionalProperties: false
CountrySummary:
type: object
description: A country and how much the directory holds for it.
properties:
iso2:
type: string
description: ISO 3166-1 alpha-2 code.
slug:
type: string
description: The country as the site's URLs write it.
name:
type: string
description: The country's name.
region_count:
type: integer
description: Regions with a page.
locality_count:
type: integer
description: Suburbs with a page.
place_count:
type: integer
description: Locations held.
required:
- iso2
- slug
- name
- region_count
- locality_count
- place_count
additionalProperties: false
PlacesResponse:
type: object
description: Places in a suburb.
properties:
data:
type: array
description: Places, by name.
items:
$ref: '#/components/schemas/Place'
generated_at:
type: string
description: When the answer was made. Answers are cached at the edge, so it can be up to an hour old.
format: date-time
next_cursor:
type: string
description: 'Reserved for paging. Never set today: the first page is the whole answer, up to limit.'
required:
- data
- generated_at
additionalProperties: false
CategoryHub:
type: object
description: 'One category across a country: counts per region and the busiest suburbs, not a list of every place.'
properties:
country:
$ref: '#/components/schemas/Country'
category:
type: string
description: The category.
enum:
- post-offices
- post-boxes
- express-post-boxes
- parcel-lockers
- drop-off-points
- collection-points
total:
type: integer
description: Places of this category in the country (or region, when narrowed).
regions:
type: array
description: Regions holding this category, busiest first.
items:
$ref: '#/components/schemas/RegionSummary'
localities:
type: array
description: The busiest suburbs for this category, up to 60.
items:
$ref: '#/components/schemas/LocalityLink'
required:
- country
- category
- total
- regions
- localities
additionalProperties: false
CountriesResponse:
type: object
description: Every country covered.
properties:
data:
type: array
description: Countries.
items:
$ref: '#/components/schemas/CountrySummary'
generated_at:
type: string
description: When the answer was made. Answers are cached at the edge, so it can be up to an hour old.
format: date-time
required:
- data
- generated_at
additionalProperties: false
PlaceDetail:
type: object
description: One place in full, with where it sits, what is close by, reviews and photos.
properties:
country:
$ref: '#/components/schemas/Country'
region:
$ref: '#/components/schemas/Region'
locality:
$ref: '#/components/schemas/Locality'
place:
$ref: '#/components/schemas/Place'
nearby:
type: array
description: Other places close by, nearest first.
items:
$ref: '#/components/schemas/PlaceLink'
reviews:
$ref: '#/components/schemas/Reviews'
photos:
type: array
description: Approved photos, newest first.
items:
$ref: '#/components/schemas/Photo'
required:
- country
- region
- locality
- place
- nearby
- reviews
- photos
additionalProperties: false
Facet:
type: object
description: One value and how many places have it.
properties:
key:
type: string
description: The category or brand key.
count:
type: integer
description: How many places.
required:
- key
- count
additionalProperties: false
Locality:
type: object
description: A suburb or town.
properties:
slug:
type: string
description: The URL segment this row has on postfinder.io.
name:
type: string
description: The suburb's name.
postcode:
type: string
description: The postcode people write for it. Absent where the country's postcodes are not held.
lat:
type: number
description: Latitude of the suburb's centre, where held.
lng:
type: number
description: Longitude of the suburb's centre, where held.
place_count:
type: integer
description: How many locations it holds.
required:
- slug
- name
- place_count
additionalProperties: false
RegionResponse:
type: object
description: One region.
properties:
data:
$ref: '#/components/schemas/RegionDetail'
generated_at:
type: string
description: When the answer was made. Answers are cached at the edge, so it can be up to an hour old.
format: date-time
required:
- data
- generated_at
additionalProperties: false
CountryDetail:
type: object
description: A country and its regions.
properties:
country:
$ref: '#/components/schemas/Country'
regions:
type: array
description: Every region with a page, largest first.
items:
$ref: '#/components/schemas/RegionSummary'
required:
- country
- regions
additionalProperties: false
LocalityResponse:
type: object
description: One suburb.
properties:
data:
$ref: '#/components/schemas/LocalityDetail'
generated_at:
type: string
description: When the answer was made. Answers are cached at the edge, so it can be up to an hour old.
format: date-time
required:
- data
- generated_at
additionalProperties: false
Country:
type: object
description: A country the directory covers.
properties:
iso2:
type: string
description: ISO 3166-1 alpha-2 code.
slug:
type: string
description: 'The country as postfinder.io''s URLs write it: australia, new-zealand.'
name:
type: string
description: The country's name.
required:
- iso2
- slug
- name
additionalProperties: false
Region:
type: object
description: A state, province or other first level division.
properties:
slug:
type: string
description: The URL segment this row has on postfinder.io.
code:
type: string
description: 'The short code, where the country has them: VIC, NSW. Absent where it has none.'
name:
type: string
description: The region's name.
required:
- slug
- name
additionalProperties: false
PlaceResponse:
type: object
description: One place.
properties:
data:
$ref: '#/components/schemas/PlaceDetail'
generated_at:
type: string
description: When the answer was made. Answers are cached at the edge, so it can be up to an hour old.
format: date-time
required:
- data
- generated_at
additionalProperties: false
LocalityDetail:
type: object
description: 'A suburb: every place in it, with facet counts and its neighbours.'
properties:
country:
$ref: '#/components/schemas/Country'
region:
$ref: '#/components/schemas/Region'
locality:
$ref: '#/components/schemas/Locality'
categories:
type: array
description: How many places of each category.
items:
$ref: '#/components/schemas/Facet'
brands:
type: array
description: How many places of each operator.
items:
$ref: '#/components/schemas/Facet'
places:
type: array
description: Every open place in the suburb.
items:
$ref: '#/components/schemas/Place'
neighbours:
type: array
description: Nearby suburbs, nearest first.
items:
$ref: '#/components/schemas/LocalityLink'
required:
- country
- region
- locality
- categories
- brands
- places
- neighbours
additionalProperties: false
LocalitySummary:
type: object
description: A suburb in a region's list.
properties:
slug:
type: string
description: The URL segment this row has on postfinder.io.
name:
type: string
description: The suburb's name.
postcode:
type: string
description: Its postcode, where held.
place_count:
type: integer
description: Locations held.
required:
- slug
- name
- place_count
additionalProperties: false
Place:
type: object
description: One post office, post box, parcel locker, drop off or collection point.
properties:
public_id:
type: string
description: 'The place''s permanent id: minted once, never reused, and the stable end of its URL.'
pattern: ^[a-z2-7]{8}$
slug:
type: string
description: The URL segment this row has on postfinder.io.
name:
type: string
description: The name on the door.
brand:
type: string
description: 'Which operator runs it, as a key: auspost, parcelpoint, nzpost.'
category:
type: string
description: What kind of place it is.
enum:
- post-offices
- post-boxes
- express-post-boxes
- parcel-lockers
- drop-off-points
- collection-points
address:
type: string
description: 'The street address, where the source gives one. Absent otherwise: most post boxes have none.'
lat:
type: number
description: Latitude.
lng:
type: number
description: Longitude.
hours:
type: object
description: 'Opening hours as the source publishes them, with a tz, the source''s own text, and a weekly map of day to open and close pairs. Open by design: sources carry extra keys (temporary closures, a counter''s separate hatch hours) and a reader should keep what it does not know.'
additionalProperties: true
attributes:
type: object
description: 'Whatever else the source says: phone, services, what can be sent or collected. Open by design, because each source names its own keys; read the ones you need.'
additionalProperties: true
last_verified_at:
type: string
description: When a source last confirmed the record.
format: date-time
closed_at:
type: string
description: When the place was recorded as closed. Only a place page shows a closed place.
format: date-time
required:
- public_id
- slug
- name
- brand
- category
- lat
- lng
additionalProperties: false
RegionDetail:
type: object
description: A region and a page of its suburbs.
properties:
country:
$ref: '#/components/schemas/Country'
region:
$ref: '#/components/schemas/Region'
localities:
type: array
description: This page of the region's suburbs, alphabetical.
items:
$ref: '#/components/schemas/LocalitySummary'
locality_total:
type: integer
description: How many suburbs the region has in all, for paging.
required:
- country
- region
- localities
- locality_total
additionalProperties: false
PlaceLink:
type: object
description: Another place close by, with enough to link to its page.
properties:
public_id:
type: string
description: The place's permanent id.
pattern: ^[a-z2-7]{8}$
slug:
type: string
description: The URL segment this row has on postfinder.io.
name:
type: string
description: The name on the door.
brand:
type: string
description: Operator key.
category:
type: string
description: What kind of place it is.
enum:
- post-offices
- post-boxes
- express-post-boxes
- parcel-lockers
- drop-off-points
- collection-points
address:
type: string
description: Street address, where held.
country:
type: string
description: Country slug.
region:
type: string
description: Region slug.
locality:
type: string
description: Suburb slug.
distance_km:
type: number
description: Straight line distance in kilometres.
required:
- public_id
- slug
- name
- brand
- category
- country
- region
- locality
- distance_km
additionalProperties: false
ReviewSummary:
type: object
description: What visitors said, summarised.
properties:
count:
type: integer
description: Approved reviews.
average:
type:
- number
- 'null'
description: Mean rating out of five, or null with no rated reviews.
last_as_listed_at:
type:
- string
- 'null'
format: date-time
description: When a visitor last found the place as listed, or null.
required:
- count
- average
- last_as_listed_at
additionalProperties: false
CategoryResponse:
type: object
description: One category across a country.
properties:
data:
$ref: '#/components/schemas/CategoryHub'
generated_at:
type: string
description: When the answer was made. Answers are cached at the edge, so it can be up to an hour old.
format: date-time
required:
- data
- generated_at
additionalProperties: false
RegionSummary:
type: object
description: A region and how much it holds.
properties:
slug:
type: string
description: The URL segment this row has on postfinder.io.
code:
type: string
description: The short code, where the country has them.
name:
type: string
description: The region's name.
locality_count:
type: integer
description: Suburbs with a page.
place_count:
type: integer
description: Locations held (on a category page, of that category only).
required:
- slug
- name
- locality_count
- place_count
additionalProperties: false
Reviews:
type: object
description: 'Approved reviews: a summary and the most recent.'
properties:
summary:
$ref: '#/components/schemas/ReviewSummary'
recent:
type: array
description: The most recent, newest first.
items:
$ref: '#/components/schemas/Review'
required:
- summary
- recent
additionalProperties: false
Problem:
type: object
description: An RFC 7807 problem. The title says what went wrong and the detail, when present, what to do about it.
properties:
type:
type: string
description: Always about:blank.
title:
type: string
description: What went wrong, in a few words.
status:
type: integer
description: The HTTP status, repeated.
detail:
type: string
description: What to do about it. May be empty.
required:
- type
- title
- status
- detail
additionalProperties: false
CountryResponse:
type: object
description: One country.
properties:
data:
$ref: '#/components/schemas/CountryDetail'
generated_at:
type: string
description: When the answer was made. Answers are cached at the edge, so it can be up to an hour old.
format: date-time
required:
- data
- generated_at
additionalProperties: false
Photo:
type: object
description: An approved photo. Fetch it at https://postfinder.io/media/{id}.
properties:
id:
type: string
description: Photo id.
credit:
type: string
description: Who took it, when they asked to be credited.
licence:
type: string
description: Its licence.
width:
type: integer
description: Pixels.
height:
type: integer
description: Pixels.
created_at:
type: string
description: When it was added.
format: date-time
required:
- id
- licence
- width
- height
- created_at
additionalProperties: false
LocalityLink:
type: object
description: Another suburb, with enough to link to its page.
properties:
country:
type: string
description: Country slug.
region:
type: string
description: Region slug.
slug:
type: string
description: The URL segment this row has on postfinder.io.
name:
type: string
description: The suburb's name.
place_count:
type: integer
description: Locations held.
distance_km:
type: number
description: Distance in kilometres from the suburb asked about; 0 where distance is not the ordering.
required:
- country
- region
- slug
- name
- place_count
- distance_km
additionalProperties: false
x-provenance:
method: harvested
publisher: Postfinder
source: https://api.postfinder.io/v1/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)