API developer documentation

All the API calls listed below return planning application sorted by the date they were scraped from the planning authority website with the most recent listed first.

The API can return different formats including JSON, GeoJSON and GeoRSS. The examples below return JSON. To get GeoJSON instead simply replace ".json" in the URL with ".geojson". For GeoRSS replace ".json" with ".rss".

To use the API you will to register for an account or sign in to your existing account. Once you've done that, return to this page and the you will be able to create an API key here.

API calls

Single Location by longitude/latitude

Return applications near a given longitude/latitude. The area included is a circle with a radius of the given size (in metres) with the longitude/latitude at its center. Suggested sizes are 400, 800 or 4000 metres.


        http://api.planningalerts.org.au/applications.json?key=[key]&lat=[latitude]&lng=[longitude]&radius=[distance_in_metres]

Area by longitude/latitude

Return applications within a rectangle defined by longitude/latitude.


        http://api.planningalerts.org.au/applications.json?bottom_left_lat=[latitude]&bottom_left_lng=[longitude]&key=[key]&top_right_lat=[latitude]&top_right_lng=[longitude]

Planning authority

Return applications for a specific planning authority (e.g. a local council) by authority short name. To discover the authority short name to use here, find the planning authority on the list of authorities and follow the link. The url has the authority short name in it.


        http://api.planningalerts.org.au/authorities/[name]/applications.json?key=[key]

Postcode

Return applications for a specific postcode area


        http://api.planningalerts.org.au/applications.json?key=[key]&postcode=[postcode]

Suburb

Return applications in a suburb. Including “state” and “postcode” in the search is optional.


        http://api.planningalerts.org.au/applications.json?key=[key]&postcode=[postcode]&state=[state]&suburb=[suburb]

Bulk API - all^*

Returns all applications ordered by numeric id. Up to 1000 records are returned in one request. To get subsequent records set the optional parameter since_id to the max_id (the maximum id) of the page you have already retrieved.


        http://api.planningalerts.org.au/applications.json?key=[key]&since_id=[since_id]

Bulk API - by date scraped^*

Returns all applications scraped on a single day. Date is in ISO 8601 format.


        http://api.planningalerts.org.au/applications.json?date_scraped=[date_scraped]&key=[key]

* Bulk API calls are available as an option in the Premium Plan.

Extra query parameters

There are several parameters that can be applied to each of the above queries (except for bulk API) for extra usefulness.

page

API calls return a maximum of 100 results. To retrieve more results simply do another request with page set to 2, 3, etc… Not setting the page parameter is the same as requesting page 1.


          http://api.planningalerts.org.au/applications.json?key=[key]&page=2&postcode=2780

count

API calls by default return a maximum of 100 results. To return less than that per page simply set the count parameter to the maximum number you want to return.


          http://api.planningalerts.org.au/applications.json?count=10&key=[key]&postcode=2780

Warning about client side API queries

Client-side API queries are supported using CORS. You might do this, for example, in a Javascript application that runs in the browser making requests directly to the Planning Alerts API. This is fine for testing. However, this should not be used in production as you would be effectively making your API key public, which is a very bad. It is your responsibility to keep the API key safe and secure.

Instead we recommend either loading the data ahead of time server-side and passing the data to your client or alternatively proxying the client-side requests through your own server where you add the API key.

Daily quota

Almost all API keys have a daily usage quota. This is based on the number of API calls made during a 24 hour period starting and ending at midnight UTC.

If you go over the limit the API request will be blocked and

The response will return a 429 Too Many Requests error code.
The body of the response will be the text "Retry later".
The response HTTP header "retry-after" will be set to the number of seconds to wait until the quota is reset.