Help pages

Contact us

If your question isn't answered here, or you just wanted to let us know something about the site, contact us.

Application Programming Interface - API

Introduction

This page explains how programmers can make other websites and software interact with Right To Know via an "API".

Right To Know does not have a full API yet, but we are gradually adding lots of things that are similar in use to an API as they are requested.


1. Linking to new requests

To assist users in making new requests you can link to a pre-filled request form. The details of which public authority the request is addressed to and the contents of the body of the request message are part of the URL.

A link to a new request for a particular public authority, uses a URL of the form https://www.righttoknow.org.au/new/defence. These are the parameters you can add to those URLs, either in a normal hyperlink or through a form.

  • title - default summary of the new request.
  • default_letter - default text of the body of the letter. The salutation (Dear...) and signoff (Yours...) are wrapped round this.
  • body - as an alternative to default_letter, this sets the default entire text of the request, so you can customise the salutation and signoff.
  • tags - space separated list of tags, so you can find and link up any requests made later, e.g. openlylocal spending_id:12345. The : indicates it is a machine tag. The values of machine tags may also include colons, useful for URIs.

Text added to these URLs must be URL encoded. You can use the URL Decoder/Encoder at meyerweb.com as a tool to help encode your text.

Within a URL, multiple parameters are divided with ampersand "&". For example, the following link uses both the title and default_letter paramaters: https://www.righttoknow.org.au/new/defence?default_letter=Test+request+body&title=Test+Request


2. RSS (actually, Atom) feeds

There are Atom feeds on most pages which list requests, which you can use to get updates and links in XML format. Find the URL of the Atom feed in one of these ways:

  • Look for the RSS feed links.
  • Examine the <link rel="alternate" type="application/atom+xml"> tag in the head of the HTML.
  • Add /feed to the start of another URL.

In particular, even complicated search queries have Atom feeds. You can do all sorts of things with them, such as query by authority, by file type, by date range, or by status. See the advanced search tips for details.


3. JSON structured data

Quite a few pages have JSON versions, which let you download information about objects in a structured form. Find them by:

  • Adding .json to the end of the URL.
  • Look for the <link rel="alternate" type="application/json"> tag in the head of the HTML.

Requests, users and authorities all have JSON versions containing basic information about them. Every Atom feed has a JSON equivalent, containing information about the list of events in the feed.


4. Spreadsheet of all authorities

A spreadsheet file listing every body in Right To Know is available: all-authorities.csv


Please contact us if you need an API feature that isn't there yet. It's very much a work in progress, and we do add things when people ask us to.