[ Whereis® API Home ] [ JSON API Home ] [ Services ] [ Resource Discovery Services ]
Use the state resources to obtain a paginated list of all states, access information about a single state or to access attributes: all regions or suburbs within a state, or metadata about the state.
List
Access a paginated list of states, optionally filtered by various parameters
List URL
HTTP GET to <ENDPOINT>/service/resources/states/?<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" |
| 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. |
Item
Access an individual state by identifier.
Item URL
HTTP GET to <ENDPOINT>/service/resources/states/<ID>/?<PARAMETERS>
Item Parameters
Parameter | Mandatory? | Description |
| id | Y | Either the real ID as defined in the list result such as "state-2" or a pseudo identifier made up of the abbreviation or full name for the state, such as "vic" or "victoria". If using a pseudo identifier, spaces in the name are replaced with a hyphen "-" character. |
| 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 Requests
<ENDPOINT>/service/resources/states/new-south-wales <ENDPOINT>/service/resources/states/state-2
Sample Response
{
"id": "state-2",
"centrePoint": {
"lon": 151.20757,
"lat": -33.870775
},
"streetPoint": {
"lon": 151.20757,
"lat": -33.870775
},
"bounds": {
"left": 141.001074,
"top": -29.012488,
"right": 153.669354,
"bottom": -37.416689
},
"approximated": false,
"granularity": "STATE",
"address": {
"state": "NSW",
"display": "NSW"
}
}
State Metadata
Return count for states, as well as count for all regions and suburbs.
State Metadata URL
HTTP GET to <ENDPOINT>/service/resources/states/metadata/?<PARAMETERS>
State Metadata Parameters
Parameter | Mandatory? | Description |
| state | N | Optional state to restrict the metadata to. Default = All states |
Sample Metadata Request
<ENDPOINT>/service/resources/states/metadata/?state=NT
Sample 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
}
}
}
}
Suburbs in State
Access a paginated list of suburbs for a given state, optionally filtered by street name.
URL
HTTP GET to <ENDPOINT>/service/resources/states/<ID>/suburbs/?<PARAMETERS>
Parameters
Parameter | Mandatory? | Description |
| id | Y | Either the real ID as defined in the list result such as "state-2" or a pseudo identifier made up of the name or abbreviation such as "nsw" or "new-south-wales". If using a pseudo identifier, spaces in the name are replaced with a hyphen "-" character. |
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" |
| 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 URL
<ENDPOINT>/service/resources/states/vic/suburbs/?details=address&size=2
Sample Response
{
"results": [
{
"address": {
"suburb": "MELBOURNE",
"suburbVanities": [
"MELB"
],
"postcode": "3000",
"regions": [
"GREATER MELBOURNE",
"MELBOURNE - INNER CITY SUBURBS",
"MELBOURNE CBD",
"MELBOURNE COUNCIL"
],
"state": "VIC",
"display": "MELBOURNE, VIC 3000"
}
},
{
"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": 2970
}
}