openaustralia/planningalerts

- content_for :page_title, "Get the Data — API"

%h3= yield :page_title

%p
  Planning application data is available programmatically. Details of the API are listed below.

%p
  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.
%p
  The API can return different formats including <a href="https://www.json.org/">JSON</a>, <a href="https://geojson.org/">GeoJSON</a> and <a href="https://www.ogc.org/standard/georss/">GeoRSS</a>.
  The examples below return JSON. To get GeoJSON instead simply replace ".json" in the URL with ".geojson". For GeoRSS replace ".json" with ".rss".

%hr
.notice
  %p
    - if current_user
      - if api_key
        The API examples below contain your API key:
        = api_key
      - else
        You need an API key to try out the examples below and use the API for yourself.
        = button_to "Create API key", profile_api_keys_path, method: :post, class: "button button-rounded"
    - else
      To use the API you will to
      = link_to "register for an account", new_user_registration_path
      or
      = link_to "sign in", new_user_session_path
      to your existing account. (Note that this is different
      than having signed up for an email alert). Once you've done that, return to this page
      and the you will be able to create an API key here.

  - if current_user.nil?
    %p
      = link_to "Register for an account", new_user_registration_path, class: "button button-rounded"
      or
      = link_to "Sign in", new_user_session_path, class: "button button-rounded"

%h4 API documentation
.apiitem
  %h5
    Single Location by longitude/latitude
  %p.apidefinition
    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.
  %code= api_example_latlong_url_html(format: "json", key: api_key)
  - if api_key
    .apiexamples
      = link_to "Example", api_example_latlong_url(format: "json", key: api_key), class: "button button-rounded"
.apiitem
  %h5
    Area by longitude/latitude
  %p.apidefinition
    Return applications within a rectangle defined by longitude/latitude.
  %code= api_example_area_url_html(format: "json", key: api_key)
  - if api_key
    .apiexamples
      = link_to "Example", api_example_area_url(format: "json", key: api_key), class: "button button-rounded"
.apiitem
  %h5
    Planning authority
  %p.apidefinition
    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
    = link_to "list of authorities", authorities_path
    and follow the link. The url has the authority short name in it.
  %code= api_example_authority_url_html(format: "json", key: api_key)
  - if api_key
    .apiexamples
      = link_to "Example", api_example_authority_url(format: "json", key: api_key), class: "button button-rounded"
.apiitem
  %h5
    Postcode
  %p.apidefinition
    Return applications for a specific postcode area
  %code= api_example_postcode_url_html(format: "json", key: api_key)
  - if api_key
    .apiexamples
      = link_to "Example", api_example_postcode_url(format: "json", key: api_key), class: "button button-rounded"
.apiitem
  %h5
    Suburb
  %p.apidefinition
    Return applications in a suburb. Including &ldquo;state&rdquo; and &ldquo;postcode&rdquo; in the search is optional.
  %code= api_example_suburb_state_and_postcode_url_html(format: "json", key: api_key)
  - if api_key
    .apiexamples
      = link_to "Example", api_example_suburb_state_and_postcode_url(format: "json", key: api_key), class: "button button-rounded"

%hr
%h4 Extra query parameters
%p
  There are several parameters that can be applied to each of the above queries for extra usefulness.
.apiitem
  %h5 page
  %p.apidefinition
    API calls return a maximum of #{Application.max_per_page} results. To retrieve more results simply do another request with page
    set to 2, 3, etc&hellip; Not setting the page parameter is the same as requesting page 1.
  %code= api_example_postcode_url_html(format: "json", key: api_key, postcode: "2780", extra_params: { page: 2 })
.apiitem
  %h5 count
  %p.apidefinition
    API calls by default return a maximum of #{Application.max_per_page} results. To return less than that per page simply set the count parameter to the maximum number you want to return.
  %code= api_example_postcode_url_html(format: "json", key: api_key, postcode: "2780", extra_params: { count: 10 })

%hr
%h4 Warning about client side API queries
%p
  Client-side API queries are supported using <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS">CORS</a>. You might do this, for example,
  in a Javascript application that runs in the browser making requests directly to the PlanningAlerts API. This is fine for testing. However, this should <strong>not be used
  in production</strong> 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.
%p
  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.

%hr
%h4#usage
  Usage
%p
  Low volume,
  %strong non&ndash;commercial
  use of the API service is free. We ask that personal and non&ndash;profit use of this service attribute the OpenAustralia Foundation on your website or application.

%p
  Standard agreements for commercial use are at
  <a href="https://www.oaf.org.au/standard-agreements/planningalerts-commercial/">oaf.org.au/standard-agreements/planningalerts-commercial</a>.
  Please
  = link_to "contact us", documentation_contact_path(reason: "I want API access or commercial use")
  for
  %strong commercial
  use. Commercial users may include Real Estate Agencies, Architects, Planners or Builders.

%p
  Also, please
  = link_to "get in touch", documentation_contact_path(reason: "I want API access or commercial use")
  if you intend to use the service on a large scale.
  In order to maintain quality of service for our API users, this service is rate limited by default to approximately 1000 requests per day.

%p
  We offer a range of paid options, from rate&ndash;limited to unlimited use of this service.

%h4#hBeNice
  Be Nice
%p
The PlanningAlerts service is intended to help people be aware of what's happening in their local neighborhood, and to enable a civil discussion about those changes.
%p
Don't use the service (or information obtained from the service) to market goods or services to individuals.
%p
Don't use the service (or information obtained from the service) to harass or intimidate a person.