Aristocles Pty Ltd Rental Prices API

openapi: 3.2.0
info:
  title: Aristocles Data Rental Prices 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: Rental Prices
  description: 'Median weekly rent by suburb, postcode, bedroom count, and property type across Australia. Quarterly data back to 2000. Current coverage: VIC (146 suburbs).'
paths:
  /v1/rental:
    get:
      tags:
      - Rental Prices
      summary: Rental API coverage
      description: 'Coverage summary: which states, how many suburbs, and the latest data period.'
      operationId: rental_metadata_v1_rental_get
      parameters:
      - 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/rental/search:
    get:
      tags:
      - Rental Prices
      summary: Search suburbs by name
      description: 'Search suburbs by partial name across Australia. Returns the latest

        all-properties median rent for each match. Pass ``state`` to scope the

        search to one state, or omit it to search everywhere.'
      operationId: search_suburbs_endpoint_v1_rental_search_get
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 100
          description: Suburb name (partial match)
          title: Q
        description: Suburb name (partial match)
        example: Geelong
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 2
            maxLength: 3
          - type: 'null'
          description: Optional state code to scope the search (e.g. VIC). Omit to search all states.
          title: State
        description: Optional state code to scope the search (e.g. VIC). Omit to search all states.
        example: VIC
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 20
          title: Limit
      - 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/rental/cheapest:
    get:
      tags:
      - Rental Prices
      summary: Most affordable suburbs
      description: Most affordable suburbs for a given bedroom count and property type, ranked by current median weekly rent.
      operationId: cheapest_suburbs_endpoint_v1_rental_cheapest_get
      parameters:
      - name: state
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 3
          description: State code
          title: State
        description: State code
        example: VIC
      - name: bedrooms
        in: query
        required: true
        schema:
          type: integer
          maximum: 6
          minimum: 1
          description: Number of bedrooms
          title: Bedrooms
        description: Number of bedrooms
        example: 2
      - name: property_type
        in: query
        required: false
        schema:
          type: string
          description: flat or house
          default: flat
          title: Property Type
        description: flat or house
        example: flat
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 20
          title: Limit
      - name: min_leases
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Minimum number of leases for statistical reliability
          default: 5
          title: Min Leases
        description: Minimum number of leases for statistical reliability
      - 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/rental/compare:
    get:
      tags:
      - Rental Prices
      summary: Compare suburbs side by side
      description: Compare rental price history across up to 10 suburbs side by side.
      operationId: compare_suburbs_endpoint_v1_rental_compare_get
      parameters:
      - name: state
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 3
          title: State
        example: VIC
      - name: suburbs
        in: query
        required: true
        schema:
          type: string
          description: Comma-separated suburb names
          title: Suburbs
        description: Comma-separated suburb names
        example: Richmond,South Yarra,Fitzroy
      - name: bedrooms
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 6
            minimum: 1
          - type: 'null'
          title: Bedrooms
      - name: property_type
        in: query
        required: false
        schema:
          type: string
          description: flat, house, or all
          default: all
          title: Property Type
        description: flat, house, or all
      - name: periods
        in: query
        required: false
        schema:
          type: integer
          maximum: 20
          minimum: 1
          description: Number of recent quarters to include
          default: 4
          title: Periods
        description: Number of recent quarters to include
      - 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/rental/trending:
    get:
      tags:
      - Rental Prices
      summary: Fastest rising and falling rents
      description: Suburbs with the biggest rent changes over the last year — either rising fastest or dropping most.
      operationId: trending_suburbs_endpoint_v1_rental_trending_get
      parameters:
      - name: state
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 3
          title: State
        example: VIC
      - name: bedrooms
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 6
            minimum: 1
          - type: 'null'
          title: Bedrooms
      - name: property_type
        in: query
        required: false
        schema:
          type: string
          description: flat or house
          default: flat
          title: Property Type
        description: flat or house
      - name: direction
        in: query
        required: false
        schema:
          type: string
          description: up = fastest rising, down = biggest drops
          default: up
          title: Direction
        description: up = fastest rising, down = biggest drops
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 20
          title: Limit
      - 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/rental/lgas:
    get:
      tags:
      - Rental Prices
      summary: List LGA region groups
      description: List all LGA / region group names for a state.
      operationId: list_lgas_endpoint_v1_rental_lgas_get
      parameters:
      - name: state
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 3
          title: State
        example: VIC
      - 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/rental/postcode/{postcode}:
    get:
      tags:
      - Rental Prices
      summary: Get rental prices by postcode
      description: 'Rental history for all suburbs that map to a given postcode.


        Example: GET /v1/rental/postcode/3121 → Richmond, Burnley (VIC)

        Example: GET /v1/rental/postcode/3121?bedrooms=2&property_type=flat'
      operationId: get_postcode_endpoint_v1_rental_postcode__postcode__get
      parameters:
      - name: postcode
        in: path
        required: true
        schema:
          type: string
          title: Postcode
      - name: bedrooms
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 6
            minimum: 1
          - type: 'null'
          title: Bedrooms
      - name: property_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: flat, house, or all
          title: Property Type
        description: flat, house, or all
      - name: periods
        in: query
        required: false
        schema:
          type: integer
          maximum: 40
          minimum: 1
          description: Number of recent quarters
          default: 8
          title: Periods
        description: Number of recent quarters
      - 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/rental/{state}/{suburb}:
    get:
      tags:
      - Rental Prices
      summary: Get suburb rental history
      description: 'Full rental history for a suburb — all property types and bedroom counts,

        for the most recent N quarters.


        Example: GET /v1/rental/VIC/Richmond'
      operationId: get_suburb_endpoint_v1_rental__state___suburb__get
      parameters:
      - name: state
        in: path
        required: true
        schema:
          type: string
          title: State
      - name: suburb
        in: path
        required: true
        schema:
          type: string
          title: Suburb
      - name: bedrooms
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 6
            minimum: 1
          - type: 'null'
          title: Bedrooms
      - name: property_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: flat, house, or all
          title: Property Type
        description: flat, house, or all
      - name: periods
        in: query
        required: false
        schema:
          type: integer
          maximum: 40
          minimum: 1
          description: Number of recent quarters
          default: 8
          title: Periods
        description: Number of recent quarters
      - 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