Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Aristocles Data Contractor/Trade Pricing API
description: 'Four Australian data APIs on one key — subscriptions, trade pricing, PBS drugs, and rental prices.
---
## Quick start
**1. Get your API key** — register in one request:
```
POST /v1/auth/register
{"email": "you@example.com", "name": "Your Name"}
```
Copy the `api_key` from the response.
**2. Authenticate** — add your key to every request as a header:
```
X-API-Key: ar_live_xxxxxxxxxxxx
```
**3. Run the discovery endpoint** — returns all available slugs, example calls, and your account limits:
```
GET /v1/discovery
```
**4. Make your first call:**
```
GET /v1/prices/netflix?country=AU
GET /v1/trades/electrician/prices?state=NSW&country=AU
GET /v1/pbs/metformin
GET /v1/rental/VIC/Richmond
```
---
## Four data domains
| Domain | Base path | What it covers |
|---|---|---|
| **Subscription Pricing** | `/v1/prices`, `/v1/services` | 50+ SaaS & streaming services: Netflix, Spotify, Adobe, etc. |
| **Contractor Trades** | `/v1/trades` | Plumbers, electricians, painters across AU, US, UK, CA, NZ |
| **PBS Drug Pricing** | `/v1/pbs` | 14,000+ medications on Australia''s Pharmaceutical Benefits Scheme |
| **Rental Market** | `/v1/rental` | Median weekly rent by suburb and postcode across Australia |
| **RBA Economic Data** | `/v1/rba` | Cash rate, AUD FX rates, CPI inflation, mortgage rates, credit aggregates |
---
## MCP Server
All four data domains are also available as MCP tools at:
```
https://api.aristocles.com.au/mcp/
```
Connect any MCP-compatible AI agent (Claude, GPT, Gemini) to get structured data without writing API calls.'
version: 2.1.0
tags:
- name: Contractor/Trade Pricing
paths:
/v1/trades/search:
get:
tags:
- Contractor/Trade Pricing
summary: Search Trades Endpoint
description: Search across all trades and trade services by name.
operationId: search_trades_endpoint_v1_trades_search_get
parameters:
- name: q
in: query
required: true
schema:
type: string
minLength: 2
maxLength: 200
description: Search query for trades and services
title: Q
description: Search query for trades and services
- name: limit
in: query
required: false
schema:
type: integer
maximum: 50
minimum: 1
description: Max results to return
default: 10
title: Limit
description: Max results to return
- name: X-API-Key
in: header
required: true
schema:
type: string
title: X-Api-Key
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/trades/compare:
get:
tags:
- Contractor/Trade Pricing
summary: Compare Trade Prices Endpoint
description: Compare prices for a trade service across multiple states.
operationId: compare_trade_prices_endpoint_v1_trades_compare_get
parameters:
- name: trade
in: query
required: true
schema:
type: string
description: Trade slug — get slugs from `GET /v1/trades`
title: Trade
description: Trade slug — get slugs from `GET /v1/trades`
example: electrician
- name: service
in: query
required: true
schema:
type: string
description: Trade service slug — get slugs from `GET /v1/trades/{slug}`
title: Service
description: Trade service slug — get slugs from `GET /v1/trades/{slug}`
example: install-power-point
- name: locations
in: query
required: true
schema:
type: string
description: Comma-separated state/region codes
title: Locations
description: Comma-separated state/region codes
example: NSW,VIC,QLD
- name: country
in: query
required: false
schema:
type: string
description: 'Country code: AU, US, UK, CA, NZ'
default: AU
title: Country
description: 'Country code: AU, US, UK, CA, NZ'
- name: X-API-Key
in: header
required: true
schema:
type: string
title: X-Api-Key
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/trades/estimate:
get:
tags:
- Contractor/Trade Pricing
summary: Estimate Cost Endpoint
description: Estimate total job cost for a trade service at a location.
operationId: estimate_cost_endpoint_v1_trades_estimate_get
parameters:
- name: trade
in: query
required: true
schema:
type: string
description: Trade slug — get slugs from `GET /v1/trades`
title: Trade
description: Trade slug — get slugs from `GET /v1/trades`
example: electrician
- name: service
in: query
required: true
schema:
type: string
description: Trade service slug — get slugs from `GET /v1/trades/{slug}`
title: Service
description: Trade service slug — get slugs from `GET /v1/trades/{slug}`
example: install-power-point
- name: quantity
in: query
required: false
schema:
type: number
exclusiveMinimum: 0
description: Quantity in the service's unit (hours, jobs, sqm — returned in results)
default: 1.0
title: Quantity
description: Quantity in the service's unit (hours, jobs, sqm — returned in results)
example: 3.0
- name: postcode
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Postcode filter, e.g. 2000 (Sydney), 3000 (Melbourne), 90210 (LA)
title: Postcode
description: Postcode filter, e.g. 2000 (Sydney), 3000 (Melbourne), 90210 (LA)
example: '2000'
- name: suburb
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Suburb or city name, e.g. Surry Hills, Brooklyn
title: Suburb
description: Suburb or city name, e.g. Surry Hills, Brooklyn
- name: state
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'State/region code: NSW, VIC, QLD, WA, SA (AU) — or CA, NY, TX (US)'
title: State
description: 'State/region code: NSW, VIC, QLD, WA, SA (AU) — or CA, NY, TX (US)'
example: NSW
- name: region
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Region name, e.g. Sydney Metro, Greater London
title: Region
description: Region name, e.g. Sydney Metro, Greater London
- name: country
in: query
required: false
schema:
type: string
description: 'Country code: AU, US, UK, CA, NZ'
default: AU
title: Country
description: 'Country code: AU, US, UK, CA, NZ'
- name: X-API-Key
in: header
required: true
schema:
type: string
title: X-Api-Key
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
example:
data:
trade_name: Electrician
service_name: Install Power Point
location_description: NSW (state-wide)
quantity: 3.0
unit: per point
price_low_per_unit: 80
price_high_per_unit: 150
price_avg_per_unit: 115
estimated_low: 240.0
estimated_high: 450.0
estimated_avg: 345.0
currency: AUD
meta:
timestamp: '2024-06-01T00:00:00Z'
source: aristocles-api
version: '1.0'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/trades:
get:
tags:
- Contractor/Trade Pricing
summary: List Trades Endpoint
description: List all available contractor trades with service counts.
operationId: list_trades_endpoint_v1_trades_get
parameters:
- name: search
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 200
- type: 'null'
description: Filter trades by name
title: Search
description: Filter trades by name
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
description: Page number
default: 1
title: Page
description: Page number
- name: per_page
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Results per page
default: 20
title: Per Page
description: Results per page
- name: X-API-Key
in: header
required: true
schema:
type: string
title: X-Api-Key
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
example:
data:
items:
- slug: carpenter
name: Carpenter
service_count: 3
- slug: electrician
name: Electrician
service_count: 4
- slug: plumber
name: Plumber
service_count: 4
total: 10
page: 1
per_page: 20
pages: 1
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/trades/{slug}/prices:
get:
tags:
- Contractor/Trade Pricing
summary: Get Trade Prices Endpoint
description: Get current prices for all services under a trade, filterable by location and country.
operationId: get_trade_prices_endpoint_v1_trades__slug__prices_get
parameters:
- name: slug
in: path
required: true
schema:
type: string
description: Trade slug — get slugs from `GET /v1/trades`
title: Slug
description: Trade slug — get slugs from `GET /v1/trades`
example: electrician
- name: service
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter to one service slug — get slugs from `GET /v1/trades/{slug}`
title: Service
description: Filter to one service slug — get slugs from `GET /v1/trades/{slug}`
example: install-power-point
- name: postcode
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Postcode filter, e.g. 2000 (Sydney), 3000 (Melbourne)
title: Postcode
description: Postcode filter, e.g. 2000 (Sydney), 3000 (Melbourne)
example: '2000'
- name: suburb
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Suburb or city name, e.g. Surry Hills
title: Suburb
description: Suburb or city name, e.g. Surry Hills
- name: state
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'State code: NSW, VIC, QLD, WA, SA, TAS, ACT, NT (AU)'
title: State
description: 'State code: NSW, VIC, QLD, WA, SA, TAS, ACT, NT (AU)'
example: NSW
- name: region
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Region name, e.g. Sydney Metro
title: Region
description: Region name, e.g. Sydney Metro
- name: country
in: query
required: false
schema:
type: string
description: 'Country code: AU, US, UK, CA, NZ'
default: AU
title: Country
description: 'Country code: AU, US, UK, CA, NZ'
- name: X-API-Key
in: header
required: true
schema:
type: string
title: X-Api-Key
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
example:
data:
- trade_slug: electrician
trade_name: Electrician
service_slug: install-power-point
service_name: Install Power Point
state: NSW
country_code: AU
price_low: 80
price_high: 150
price_avg: 115
currency: AUD
unit: per point
source: Service Seeking
is_current: true
effective_date: '2024-06-01'
meta:
timestamp: '2024-06-01T00:00:00Z'
source: aristocles-api
version: '1.0'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/trades/{slug}/cheapest-location:
get:
tags:
- Contractor/Trade Pricing
summary: Cheapest Location Endpoint
description: Find the cheapest state/region for a given trade service in a country.
operationId: cheapest_location_endpoint_v1_trades__slug__cheapest_location_get
parameters:
- name: slug
in: path
required: true
schema:
type: string
description: Trade slug — get slugs from `GET /v1/trades`
title: Slug
description: Trade slug — get slugs from `GET /v1/trades`
example: electrician
- name: service
in: query
required: true
schema:
type: string
description: Trade service slug — get slugs from `GET /v1/trades/{slug}`
title: Service
description: Trade service slug — get slugs from `GET /v1/trades/{slug}`
example: hourly-rate
- name: states
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated state codes to compare (defaults to all states in country)
title: States
description: Comma-separated state codes to compare (defaults to all states in country)
example: NSW,VIC,QLD
- name: country
in: query
required: false
schema:
type: string
description: 'Country code: AU, US, UK, CA, NZ'
default: AU
title: Country
description: 'Country code: AU, US, UK, CA, NZ'
- name: X-API-Key
in: header
required: true
schema:
type: string
title: X-Api-Key
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/trades/{slug}/history:
get:
tags:
- Contractor/Trade Pricing
summary: Get Trade Price History Endpoint
description: 'Historical price snapshots for a trade service, grouped by location.
Shows how prices have changed over time with percentage change between snapshots.
Data refreshes quarterly — use `is_current: true` to identify the latest snapshot.'
operationId: get_trade_price_history_endpoint_v1_trades__slug__history_get
parameters:
- name: slug
in: path
required: true
schema:
type: string
description: Trade slug — get slugs from `GET /v1/trades`
title: Slug
description: Trade slug — get slugs from `GET /v1/trades`
example: electrician
- name: service
in: query
required: true
schema:
type: string
description: Trade service slug — get slugs from `GET /v1/trades/{slug}`
title: Service
description: Trade service slug — get slugs from `GET /v1/trades/{slug}`
example: hourly-rate
- name: state
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter to a specific state, e.g. NSW, VIC
title: State
description: Filter to a specific state, e.g. NSW, VIC
example: NSW
- name: country
in: query
required: false
schema:
type: string
description: 'Country code: AU, US, UK, CA, NZ'
default: AU
title: Country
description: 'Country code: AU, US, UK, CA, NZ'
- name: X-API-Key
in: header
required: true
schema:
type: string
title: X-Api-Key
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/trades/{slug}:
get:
tags:
- Contractor/Trade Pricing
summary: Get Trade Endpoint
description: Get trade detail with all its services.
operationId: get_trade_endpoint_v1_trades__slug__get
parameters:
- name: slug
in: path
required: true
schema:
type: string
description: Trade slug — get slugs from `GET /v1/trades`
title: Slug
description: Trade slug — get slugs from `GET /v1/trades`
example: electrician
- name: X-API-Key
in: header
required: true
schema:
type: string
title: X-Api-Key
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError