Core concepts
Response formats
One query parameter changes the shape of the answer. Pick the format that matches where the data is going, rather than converting it yourself on the other end.
Ask with ?format
| Value | Content type | Use it when |
|---|---|---|
| geojson | application/geo+json | The default. Drawing a map. Drops into Leaflet, Mapbox or MapLibre untouched. |
| json | application/json | You want the records without GeoJSON Feature wrapping. |
| csv | text/csv | A spreadsheet, a BI tool, or a colleague who does not want an API. Developer plan and above. |
| cap-atom | application/atom+xml | Feeding a warning system that speaks CAP. Standards validated. Developer plan and above. |
| cap-au | application/xml | Deprecated. Kept only for existing integrations, see below. Developer plan and above. |
GeoJSON and JSON are on every plan, including free. CSV, CAP Atom and the deprecated CAP-AU wrapper need the Developer plan or above; asking for one on a lower plan returns 403 with a link to the pricing page rather than a partial response.
# GeoJSON, the default curl "https://dataquoll.io/api/v1/incidents?state=nsw" \ -H "Authorization: Bearer YOUR_API_KEY" # CSV for a spreadsheet curl "https://dataquoll.io/api/v1/incidents?state=nsw&format=csv" \ -H "Authorization: Bearer YOUR_API_KEY"
GeoJSON is the default for a reason
Every incident carries geometry, and GeoJSON is the format mapping libraries already understand. Coordinates are always [lng, lat] per the standard, which is worth stating because several of the underlying government feeds publish the reverse and one publishes them as strings. Normalising that is our problem, not yours.
Larger incidents carry polygon boundaries rather than a single point, so a fire renders as its actual extent where the source publishes one.
CSV is flat on purpose
The CSV columns are: id, state, agency, feed_id, title, event_type, status, warning_level, severity, urgency, certainty, lng, lat, address, suburb, lga, location_state, reported_at, updated_at, fetched_at, is_retracted, retracted_at, retraction_reason, feature_type, event_category.
A text cell begins with a single quote (') when its first visible character is =, +, - or @ (also after spaces or line breaks, and in fullwidth form), or when it starts with a tab, a carriage return or a single quote. A spreadsheet then opens it as text and never runs it as a formula. Numbers, such as a negative latitude, are never changed. A cell holding a comma, semicolon, tab, double quote or line break is wrapped in double quotes, so a spreadsheet that splits on semicolons or tabs keeps it whole. To get the original text in code, remove one single quote from the start of any cell that begins with one.
The per-incident details object is agency-specific and does not flatten cleanly, so it is not in the CSV. If you need it, use GeoJSON or JSON and read the incident details fields guide for what each feed emits.
CAP Atom, and the deprecated wrapper
cap-atom returns a standards-validated Atom feed where each entry inlines a CAP-AU alert. Incidents retracted in the last seven days appear as Cancel messages, which is what a downstream warning system needs in order to stand them down rather than leave them on a screen.
cap-au is the older non-standard <alerts> wrapper. It still works, and it responds with a Deprecation: true header and a Link pointing at its successor. New integrations should use cap-atom.
A CAP message is an alert. A forecast record (featureType=forecast, such as a day of a fire danger forecast) is not one, so it never appears in either CAP format, and asking for forecasts as cap-atom or cap-au returns 400. Ask for them as GeoJSON, JSON or CSV.
Attribution travels with the data
Every response carries an attribution field. Most of our sources publish under Creative Commons licences that require the credit to be displayed, so if you are putting this in front of users, that field is not decorative. The attribution endpoint lists every source with its licence, and flags each one as a licensed statutory feed or not. The community-decoded pager feeds and NT PFES, an agency feed whose licence is not published, are the ones flagged not.