[ Whereis® API Home ] [ JSON API Home ] [ Services ] [ Resource Discovery Services ]
Use the region resources to obtain a paginated list of all postcodes, access information about a single postcode or access attributes: all suburbs within a postcode or metadata about the postcode.
List
Access a paginated list of postcodes, optionally filtered by state.
List URL
HTTP GET to <ENDPOINT>/service/resources/postcodes/?<PARAMETERS>
List Parameters
Parameter | Mandatory? | Description |
query | N | A wildcard filter on the postcode. For example a query of: "3*" will return all postcodes starting with "3" |
state | N | An optional state to restrict the postcodes to. Default will show postcodes from all states. |
sort | N | The sorting order of the results. This maybe one of the following: "POPULARITY" = Order by what is defined as the most "popular" postcodes. "ALPHABETIC" = Order by alphabetical (numeric) order of the postcode. Default = "POPULARITY" |
| details | N | Either a multiple value parameter or comma separated list of JSON attributes to be shown in the result. This allows showing only the parts of the postcode information. Handy to keep response sizes smaller for large lists. Default = "id", "address", "centrePoint", "streetPoint", "bounds", "granularity" |
size | N | maximum number of results to return. Min = 1 Default = 20 |
start | N | First result to return. If "size" is 20 and your request returns a "total" of 30, submit a second request with "start" = 21 to retrieve the remaining results. |
Sample List Request
<ENDPOINT>/service/resources/postcodes/?query=3*&state=VIC&details=id&details=address&size=2
Sample List Response
{
"results": [
{
"id": "postcode-3000",
"address": {
"postcode": "3000",
"regions": [
"GREATER MELBOURNE",
"MELBOURNE - INNER CITY SUBURBS",
"MELBOURNE CBD",
"MELBOURNE COUNCIL"
],
"state": "VIC",
"display": "VIC 3000"
}
},
{
"id": "postcode-3001",
"address": {
"postcode": "3001",
"regions": [
"GREATER MELBOURNE",
"MELBOURNE - INNER CITY SUBURBS",
"MELBOURNE CBD",
"MELBOURNE COUNCIL"
],
"state": "VIC",
"display": "VIC 3001"
}
}
],
"pagination": {
"start": 0,
"total": 719
}
}
Item
Access an individual postcode by identifier.
Item URL
HTTP GET to <ENDPOINT>/service/resources/postcodes/<ID>/?<PARAMETERS>
Item Parameters
Parameter | Mandatory? | Description |
| id | Y | Either the real ID as defined in the list result or a the actual four digit postcode. If using a pseudo identifier, spaces in the name are replaced with a hyphen "-" character and it is assumed that if a state is given, it is at the end. |
| details | N | Either a multiple value parameter or comma separated list of JSON attributes to be shown in the result. This allows showing only the parts of the suburb information. Handy to keep response sizes smaller for large lists. Default = "id", "address", "centrePoint", "streetPoint", "bounds", "granularity" |
Sample Request
<ENDPOINT>/service/resources/postcodes/3121/?details=address,bounds
Sample Response
{
"bounds": {
"left": 144.987899897,
"top": -37.8096123944,
"right": 145.028361181,
"bottom": -37.8345285984
},
"address": {
"postcode": "3121",
"regions": [
"BOROONDARA COUNCIL",
"GREATER MELBOURNE",
"MELBOURNE - EASTERN SUBURBS",
"MELBOURNE - INNER CITY SUBURBS",
"MELBOURNE COUNCIL",
"STONNINGTON COUNCIL",
"YARRA COUNCIL"
],
"state": "VIC",
"display": "VIC 3121"
}
}
Postcode Metadata
Return the postcode counts starting with a given letter. This is optionally filtered by state.
Postcode Metadata URL
HTTP GET to <ENDPOINT>/service/resources/postcodes/metadata/?<PARAMETERS>
Postcode Metadata Parameters
Parameter | Mandatory? | Description |
| state | N | Optional state to restrict the metadata to. Default = All states |
Sample Postocde Metadata Request
<ENDPOINT>/service/resources/postcodes/metadata/?state=nsw
Sample Postcode Metadata Response
{
"navigators": {
"postcodes": {
"name": {
"1": 318,
"2": 641,
"4": 1
}
}
}
}
Postcode suburbs
Access a paginated list of suburbs contained within a given postcode, optionally filtered by suburb name.
Postcode Suburbs URL
HTTP GET to <ENDPOINT>/service/resources/postcodes/<ID>/suburbs/?<PARAMETERS>
Postcode Suburbs Parameters
Parameter | Mandatory? | Description |
| id | Y | Either the real ID as defined in the list result, or a pseudo identifier made up of the postcode, such as 3000. If using a pseudo identifier, spaces in the name are replaced with a hyphen "-" character and it is assumed that if a state is given, it is at the end. |
query | N | A wildcard filter on the name of the street. For example a query of: "m*" will return all suburbs with in the given region starting with the letter "m" |
| details | N | Either a multiple value parameter or comma separated list of JSON attributes to be shown in the result. This allows showing only the parts of the suburb information. Handy to keep response sizes smaller for large lists. Default = "id", "address", "centrePoint", "streetPoint", "bounds", "granularity" |
size | N | maximum number of results to return. Min = 1 Default = 20 |
start | N | First result to return. If "size" is 20 and your request returns a "total" of 30, submit a second request with "start" = 21 to retrieve the remaining results. |
Postcode Suburbs URL
<ENDPOINT>/service/resources/postcodes/3121/suburbs?size=1
Sample Postcode Suburbs Response
{
"results": [
{
"id": "suburb-28265",
"centrePoint": {
"lon": 145.001542,
"lat": -37.818852
},
"streetPoint": {
"lon": 145.001542,
"lat": -37.818852
},
"bounds": {
"left": 144.988844582,
"top": -37.8096123944,
"right": 145.016871581,
"bottom": -37.8345285984
},
"approximated": false,
"granularity": "SUBURB",
"address": {
"suburb": "RICHMOND",
"suburbVanities": [
"RICHMOND EAST",
"RICHMOND NORTH",
"RICHMOND SOUTH",
"RICHMOND WEST"
],
"postcode": "3121",
"regions": [
"BOROONDARA COUNCIL",
"GREATER MELBOURNE",
"MELBOURNE - INNER CITY SUBURBS",
"MELBOURNE COUNCIL",
"STONNINGTON COUNCIL",
"YARRA COUNCIL"
],
"state": "VIC",
"display": "RICHMOND, VIC 3121"
}
}
],
"pagination": {
"start": 0,
"total": 3
}
}