[ Whereis® API Home ] [ JSON API Home ] [ Services ] [ Resource Discovery Services ]
Use the suburb resources to obtain a paginated list of all suburbs, access information about a single suburb or access attributes: all streets with a suburb or metadata about the suburb.
List
Access a paginated list of suburbs, optionally filtered by state and suburb name.
List URL
HTTP GET to <ENDPOINT>/service/resources/suburbs/?<PARAMETERS>
List Parameters
Parameter | Mandatory? | Description |
query | N | A wildcard filter on the name of the suburb. For example a query of: "m*" will return all suburbs starting with the letter "m" |
state | N | An optional state to restrict the suburbs to. Default will show suburbs 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" suburbs. "ALPHABETIC" = Order by alphabetical order of the suburb name. 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 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. |
Sample List Request
<ENDPOINT>/service/resources/suburbs/?query=m*&state=VIC&details=id&details=address&size=2
Sample List Response
{
"results": [
{
"id": "suburb-28195",
"address": {
"suburb": "MELBOURNE",
"suburbVanities": [
"MELB"
],
"postcode": "3000",
"regions": [
"GREATER MELBOURNE",
"MELBOURNE - INNER CITY SUBURBS",
"MELBOURNE CBD",
"MELBOURNE COUNCIL"
],
"state": "VIC",
"display": "MELBOURNE, VIC 3000"
}
},
{
"id": "suburb-28238",
"address": {
"suburb": "MT WAVERLEY",
"suburbVanities": [
"JORDANVILLE",
"MOUNT WAVERLEY",
"PINEWOOD"
],
"postcode": "3149",
"regions": [
"GREATER MELBOURNE",
"MELBOURNE - EASTERN SUBURBS",
"MONASH COUNCIL",
"WHITEHORSE COUNCIL"
],
"state": "VIC",
"display": "MT WAVERLEY, VIC 3149"
}
}
],
"pagination": {
"start": 0,
"total": 309
}
}
Item
Access an individual suburb by identifier.
Item URL
HTTP GET to <ENDPOINT>/service/resources/suburbs/<ID>/?<PARAMETERS>
Item Parameters
Parameter | Mandatory? | Description |
| id | Y | Either the real ID as defined in the list result such as "suburb-28238" or a pseudo identifier made up of the name and optional postcode and/or state such as "melbourne", "melbourne-3000", "melbourne-vic-3000", "melbourne-vic" or "melbourne-3000-vic". If using a pseudo identifier, spaces in the name are replaced with a hyphen "-" character and it is assumed that if a postcode or state is given, they are at the end, in no particular order. If the suburb is ambiguous, such as "richmond", the most popular suburb will be returned. In the case of "richmond" it will be Richmond, VIC. |
| 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/suburbs/north-melbourne-vic-3051/?details=address,bounds
Sample Response
{
"bounds": {
"left": 144.93528168,
"top": -37.787465184,
"right": 144.958457444,
"bottom": -37.806148877
},
"address": {
"suburb": "NORTH MELBOURNE",
"suburbVanities": [
"HOTHAM HILL",
"MACAULAY",
"MELBOURNE NORTH",
"NTH MELBOURNE",
"N MELBOURNE",
"MELBOURNE N",
"MELBOURNE NTH"
],
"postcode": "3051",
"regions": [
"GREATER MELBOURNE",
"MELBOURNE - INNER CITY SUBURBS",
"MELBOURNE COUNCIL",
"MOONEE VALLEY COUNCIL"
],
"state": "VIC",
"display": "NORTH MELBOURNE, VIC 3051"
}
}
Suburb Metadata
Return the suburb counts starting with a given letter. This is optionally filtered by state.
Suburb Metadata URL
HTTP GET to <ENDPOINT>/service/resources/suburbs/metadata/?<PARAMETERS>
Suburb Metadata Parameters
Parameter | Mandatory? | Description |
| state | N | Optional state to restrict the metadata to. Default = All states |
Sample Suburb Metadata Request
<ENDPOINT>/service/resources/suburbs/metadata/?state=NT
Sample Suburb Metadata Response
{
"navigators": {
"suburbs": {
"name": {
"A": 20,
"B": 28,
"C": 21,
"D": 18,
"E": 11,
"F": 10,
"G": 14,
"H": 13,
"I": 3,
"J": 4,
"K": 11,
"L": 17,
"M": 32,
"N": 15,
"P": 12,
"R": 9,
"S": 10,
"T": 20,
"U": 3,
"V": 5,
"W": 22,
"Y": 6,
"Z": 1
}
}
}
}
Suburb Streets
Access a paginated list of streets for a given suburb, optionally filtered by street name.
Suburb Streets URL
HTTP GET to <ENDPOINT>/service/resources/suburbs/<ID>/streets/?<PARAMETERS>
Suburb Streets Parameters
Parameter | Mandatory? | Description |
| id | Y | Either the real ID as defined in the list result such as "suburb-28238" or a pseudo identifier made up of the name and optional postcode and/or state such as "melbourne", "melbourne-3000", "melbourne-vic-3000", "melbourne-vic" or "melbourne-3000-vic". If using a pseudo identifier, spaces in the name are replaced with a hyphen "-" character and it is assumed that if a postcode or state is given, they are at the end, in no particular order. If the suburb is ambiguous, such as "richmond", the most popular suburb will be returned. In the case of "richmond" it will be Richmond, VIC. |
query | N | A wildcard filter on the name of the street. For example a query of: "m*" will return all streets with in the given suburb 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. |
Sample Suburb Streets URL
<ENDPOINT>/service/resources/suburbs/melbourne/streets?query=lon*&details=address
Sample Suburb Streets Response
{
"results": [
{
"address": {
"street": {
"name": "LONSDALE",
"type": "LA",
"display": "LONSDALE LA"
},
"suburb": "MELBOURNE",
"suburbVanities": [
"MELB"
],
"postcode": "3000",
"regions": [
"GREATER MELBOURNE",
"MELBOURNE - INNER CITY SUBURBS",
"MELBOURNE CBD",
"MELBOURNE COUNCIL"
],
"state": "VIC",
"display": "LONSDALE LA, MELBOURNE, VIC 3000"
}
},
{
"address": {
"street": {
"name": "LONSDALE",
"type": "ST",
"display": "LONSDALE ST"
},
"suburb": "MELBOURNE",
"suburbVanities": [
"MELB"
],
"postcode": "3000",
"regions": [
"GREATER MELBOURNE",
"MELBOURNE - INNER CITY SUBURBS",
"MELBOURNE CBD",
"MELBOURNE COUNCIL"
],
"state": "VIC",
"display": "LONSDALE ST, MELBOURNE, VIC 3000"
}
}
],
"pagination": {
"start": 0,
"total": 2
}
}