Gov APIato.gov.au ↗
Search and retrieve Australian Taxation Office rulings, legislation, cases, and interpretative decisions via 2 structured endpoints.
What is the Gov API?
The ATO Legal Database API provides 2 endpoints to search and retrieve documents from the Australian Taxation Office's legal database, covering rulings, legislation, tax cases, and interpretative decisions. The search endpoint returns paginated result sets with titles, document IDs, and summaries, while get_document fetches the full text and Dublin Core metadata for any specific document by its ID.
curl -X POST 'https://api.parse.bot/scraper/c8804139-5c5d-4afa-aaff-865865d5d06e/search' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"page": "1",
"query": "income tax",
"page_size": "10",
"category": "E:::Rulings",
"exact_phrase": "true",
"include_archived": "false"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace ato-gov-au-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: ATO Legal Database SDK — search rulings, drill into full documents."""
from parse_apis.ato_gov_au_api import AtoLegalDatabase, DocumentNotFound
client = AtoLegalDatabase()
# Search for superannuation-related documents, cap at 5 results.
for result in client.document_summaries.search(query="superannuation fund", limit=5):
print(result.title, "|", result.summary[:80])
# Drill down: take the first hit and fetch its full document via typed navigation.
hit = client.document_summaries.search(query="income tax deduction", limit=1).first()
if hit is not None:
doc = hit.details()
print(doc.metadata.title)
print("Type:", doc.metadata.document_type)
print("Valid from:", doc.metadata.valid_from)
print("Keywords:", doc.metadata.keywords)
print("Content preview:", doc.content[:200])
# Point lookup by a known document ID discovered from the previous search.
if hit is not None:
try:
full = client.documents.get(doc_id=hit.doc_id)
print(full.metadata.identifier, full.metadata.date_issued)
except DocumentNotFound:
print("Document no longer available")
print("exercised: document_summaries.search / details / documents.get")
Search the ATO Legal Database for documents matching a query. Returns paginated results with document titles, IDs, and summaries. Supports filtering by document category and toggling between exact phrase and keyword search. The page parameter controls which page of results to return (default 1), and page_size controls results per page (default 10).
| Param | Type | Description |
|---|---|---|
| page | integer | Page number of results to return. |
| queryrequired | string | Search terms to find in the legal database. |
| category | string | Category filter code to refine results. Format is a code string with separator ':::' (e.g. 'E:::Rulings', 'JA:::ATO interpretative decisions', 'C-CY:::Cases', 'A+B+FI:::Legislation'). Omitting returns results from all categories. |
| page_size | integer | Number of results per page (1-100). |
| exact_phrase | boolean | When true, searches for the exact phrase. When false, searches for any of the words. |
| include_archived | boolean | When true, includes archived content in search results. |
{
"type": "object",
"fields": {
"total": "total number of matching documents",
"results": "array of search result objects, each with title, doc_id, and summary",
"page_size": "number of results per page",
"total_pages": "total number of pages available",
"current_page": "current page number"
},
"sample": {
"data": {
"total": 77597,
"results": [
{
"title": "ATO ID 2015/17",
"doc_id": "AID/AID201517/00001",
"summary": "Income taxCan a trustee of a complying superannuation fund make a choice under subsection 295-465(4) of the Income Tax Assessment Act 1997 (ITAA 1997) to claim a deduction under section 295-470 of the ITAA 1997 instead, after the death of an insured fund member?"
}
],
"page_size": 10,
"total_pages": 7760,
"current_page": 1
},
"status": "success"
}
}About the Gov API
Search the ATO Legal Database
The search endpoint accepts a required query string and returns a paginated list of matching documents. Each result object includes a title, doc_id, and summary. You can control pagination with page and page_size (1–100 results per page), and the response also returns total, total_pages, and current_page so you can walk through large result sets programmatically. The exact_phrase boolean switches between phrase-match and keyword-match behaviour. Setting include_archived to true widens results to include superseded or withdrawn documents.
Filter by Document Category
The category parameter uses a code-plus-label format separated by ::: — for example, E:::Rulings or JA:::Cases. This lets you scope queries to a specific document type rather than searching across the full database. Category codes correspond to the ATO's own classification scheme, so you can target tax rulings, public rulings, legislative instruments, or case law independently.
Retrieve Full Document Content
The get_document endpoint takes a doc_id (obtained from search results, e.g. GST/GSTR20141/NAT/ATO/00001) and returns two top-level fields: content with the full document text, and metadata containing Dublin Core fields including identifier, document_type, date_created, date_issued, valid_from, valid_to, title, and subject. The valid_from and valid_to fields are particularly useful for determining whether a ruling or decision is currently operative.
The Gov API is a managed, monitored endpoint for ato.gov.au — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ato.gov.au changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official ato.gov.au API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Checking whether a specific ATO ruling is currently valid using
valid_fromandvalid_tometadata fields - Building a tax research tool that lets users search rulings by keyword and browse paginated results
- Monitoring new ATO interpretative decisions by querying the database with category filters and sorted by date
- Extracting the full text of tax cases for natural language processing or legal analytics pipelines
- Archiving all documents in a category by iterating paginated search results and fetching each
doc_id - Comparing historical and current versions of ATO guidance by including archived content with
include_archived: true - Cross-referencing ATO document subjects against a taxonomy using the
subjectfield from Dublin Core metadata
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does the ATO have an official developer API for its Legal Database?+
What does the `get_document` endpoint return beyond the document text?+
content field, the response includes a metadata object with Dublin Core fields: identifier, document_type, date_created, date_issued, valid_from, valid_to, title, and subject. The valid_from and valid_to fields indicate the operative period of a ruling or decision, which is essential for determining current applicability.How do category filters work in the search endpoint?+
category parameter accepts a code string in the format CODE:::Label, for example E:::Rulings. This restricts results to a specific document classification within the ATO Legal Database. If omitted, the search runs across all document types. You need to know the correct category code in advance; the API does not currently expose an endpoint to list available category codes.Does the API expose related documents, citations, or legislative cross-references?+
get_document, and title/summary/doc_id via search. Citation relationships and cross-references between ATO documents are not returned as structured fields. You can fork this API on Parse and revise it to add an endpoint that extracts and returns citation links from document content.Are there any limitations on retrieving very old or archived ATO documents?+
include_archived to true in the search endpoint includes them. Once you have a doc_id for an archived document, get_document will retrieve it in the same format as current documents. Availability depends on whether the document exists in the ATO Legal Database; documents never published there will not appear in results.