openapi: 3.2.0
info:
  title: Microburbs Property Data Property - Basics API
  summary: Suburb and property data for every Australian locality.
  description: '**One REST API for demographics, market indicators, risk scores, AVM and

    ranking — backed by 25+ years of Australian transactions and census data.**


    ```bash

    curl ''https://api.microburbs.com.au/v1/properties/GANSW704074813/profile'' \

    -H ''Authorization: Bearer test''

    ```


    ## Why Microburbs


    - **Data depth** — Demographics, lifestyle, risk, market, AVM and growth forecasts — all keyed to the same national suburb and property graph.'
  version: 1.0.0
servers:
- url: https://api.microburbs.com.au
  description: Production
security:
- BearerAuth: []
tags:
- name: Property - Basics
  description: Bedroom, bathroom, parking, dwelling type, lot size.
paths:
  /v1/properties/{gnaf_id}/basics/bed-count:
    get:
      tags:
      - Property - Basics
      summary: Bedroom count
      description: 'Bedroom count from the latest matching listing.


        **Price: 5¢ per call.**'
      operationId: get_property_bed_count_v1_properties__gnaf_id__basics_bed_count_get
      parameters:
      - name: gnaf_id
        in: path
        required: true
        schema:
          type: string
          title: Gnaf Id
          example: GANSW704074813
        example: GANSW704074813
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_BedCount_'
              example:
                data:
                  bed_count: 4
          headers:
            X-Cost-Cents:
              description: Exact cents billed for this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Spent-Cents:
              description: Cumulative cents Autumn reports used for this prepaid wallet.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Remaining-Cents:
              description: Spendable prepaid credit left after this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Period-End:
              description: Start of the next UTC calendar month. Prepaid credit does not expire at this timestamp.
              required: true
              schema:
                type: string
                format: date-time
            X-Balance-Cents:
              description: Compatibility alias of X-Remaining-Cents.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Rate-Card-Version:
              description: Version of the endpoint rate card used for this call.
              required: true
              schema:
                type: integer
                minimum: 1
            X-Request-Id:
              description: Request identifier to quote in support requests.
              required: true
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              example:
                detail:
                - type: missing
                  loc:
                  - query
                  - address
                  msg: Field required
                  input: null
      x-price-cents: 5
  /v1/properties/{gnaf_id}/basics/bath-count:
    get:
      tags:
      - Property - Basics
      summary: Bathroom count
      description: 'Bathroom count from the latest matching listing.


        **Price: 5¢ per call.**'
      operationId: get_property_bath_count_v1_properties__gnaf_id__basics_bath_count_get
      parameters:
      - name: gnaf_id
        in: path
        required: true
        schema:
          type: string
          title: Gnaf Id
          example: GANSW704074813
        example: GANSW704074813
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_BathCount_'
              example:
                data:
                  bath_count: 2
          headers:
            X-Cost-Cents:
              description: Exact cents billed for this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Spent-Cents:
              description: Cumulative cents Autumn reports used for this prepaid wallet.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Remaining-Cents:
              description: Spendable prepaid credit left after this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Period-End:
              description: Start of the next UTC calendar month. Prepaid credit does not expire at this timestamp.
              required: true
              schema:
                type: string
                format: date-time
            X-Balance-Cents:
              description: Compatibility alias of X-Remaining-Cents.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Rate-Card-Version:
              description: Version of the endpoint rate card used for this call.
              required: true
              schema:
                type: integer
                minimum: 1
            X-Request-Id:
              description: Request identifier to quote in support requests.
              required: true
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              example:
                detail:
                - type: missing
                  loc:
                  - query
                  - address
                  msg: Field required
                  input: null
      x-price-cents: 5
  /v1/properties/{gnaf_id}/basics/parking-count:
    get:
      tags:
      - Property - Basics
      summary: Parking-space count
      description: 'Parking-space count from the latest matching listing.


        **Price: 5¢ per call.**'
      operationId: get_property_parking_count_v1_properties__gnaf_id__basics_parking_count_get
      parameters:
      - name: gnaf_id
        in: path
        required: true
        schema:
          type: string
          title: Gnaf Id
          example: GANSW704074813
        example: GANSW704074813
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_ParkingCount_'
              example:
                data:
                  parking_count: 5
          headers:
            X-Cost-Cents:
              description: Exact cents billed for this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Spent-Cents:
              description: Cumulative cents Autumn reports used for this prepaid wallet.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Remaining-Cents:
              description: Spendable prepaid credit left after this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Period-End:
              description: Start of the next UTC calendar month. Prepaid credit does not expire at this timestamp.
              required: true
              schema:
                type: string
                format: date-time
            X-Balance-Cents:
              description: Compatibility alias of X-Remaining-Cents.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Rate-Card-Version:
              description: Version of the endpoint rate card used for this call.
              required: true
              schema:
                type: integer
                minimum: 1
            X-Request-Id:
              description: Request identifier to quote in support requests.
              required: true
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              example:
                detail:
                - type: missing
                  loc:
                  - query
                  - address
                  msg: Field required
                  input: null
      x-price-cents: 5
  /v1/properties/{gnaf_id}/basics/dwelling-type:
    get:
      tags:
      - Property - Basics
      summary: Dwelling type
      description: 'Dwelling type (house, unit, townhouse, ...).


        **Price: 5¢ per call.**'
      operationId: get_property_dwelling_type_v1_properties__gnaf_id__basics_dwelling_type_get
      parameters:
      - name: gnaf_id
        in: path
        required: true
        schema:
          type: string
          title: Gnaf Id
          example: GANSW704074813
        example: GANSW704074813
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_DwellingType_'
              example:
                data:
                  dwelling_type: house
          headers:
            X-Cost-Cents:
              description: Exact cents billed for this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Spent-Cents:
              description: Cumulative cents Autumn reports used for this prepaid wallet.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Remaining-Cents:
              description: Spendable prepaid credit left after this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Period-End:
              description: Start of the next UTC calendar month. Prepaid credit does not expire at this timestamp.
              required: true
              schema:
                type: string
                format: date-time
            X-Balance-Cents:
              description: Compatibility alias of X-Remaining-Cents.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Rate-Card-Version:
              description: Version of the endpoint rate card used for this call.
              required: true
              schema:
                type: integer
                minimum: 1
            X-Request-Id:
              description: Request identifier to quote in support requests.
              required: true
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              example:
                detail:
                - type: missing
                  loc:
                  - query
                  - address
                  msg: Field required
                  input: null
      x-price-cents: 5
  /v1/properties/{gnaf_id}/basics/land-area-sqm:
    get:
      tags:
      - Property - Basics
      summary: Land area (sqm)
      description: 'Parcel land area in square metres from the cadastral feed.


        **Price: 3¢ per call.**'
      operationId: get_property_land_area_sqm_v1_properties__gnaf_id__basics_land_area_sqm_get
      parameters:
      - name: gnaf_id
        in: path
        required: true
        schema:
          type: string
          title: Gnaf Id
          example: GANSW704074813
        example: GANSW704074813
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_LandAreaSqm_'
              example:
                data:
                  land_area_sqm: 814.0
          headers:
            X-Cost-Cents:
              description: Exact cents billed for this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Spent-Cents:
              description: Cumulative cents Autumn reports used for this prepaid wallet.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Remaining-Cents:
              description: Spendable prepaid credit left after this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Period-End:
              description: Start of the next UTC calendar month. Prepaid credit does not expire at this timestamp.
              required: true
              schema:
                type: string
                format: date-time
            X-Balance-Cents:
              description: Compatibility alias of X-Remaining-Cents.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Rate-Card-Version:
              description: Version of the endpoint rate card used for this call.
              required: true
              schema:
                type: integer
                minimum: 1
            X-Request-Id:
              description: Request identifier to quote in support requests.
              required: true
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              example:
                detail:
                - type: missing
                  loc:
                  - query
                  - address
                  msg: Field required
                  input: null
      x-price-cents: 3
  /v1/properties/{gnaf_id}/basics/all:
    get:
      tags:
      - Property - Basics
      summary: All basics — bundle
      description: '**Price: 23¢ per call.**'
      operationId: get_property_basics_all_v1_properties__gnaf_id__basics_all_get
      parameters:
      - name: gnaf_id
        in: path
        required: true
        schema:
          type: string
          title: Gnaf Id
          example: GANSW704074813
        example: GANSW704074813
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_BasicsAll_'
              example:
                data:
                  bath_count: 2
                  bed_count: 4
                  dwelling_type: house
                  land_area_sqm: 814.0
                  parking_count: 5
          headers:
            X-Cost-Cents:
              description: Exact cents billed for this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Spent-Cents:
              description: Cumulative cents Autumn reports used for this prepaid wallet.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Remaining-Cents:
              description: Spendable prepaid credit left after this call.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Period-End:
              description: Start of the next UTC calendar month. Prepaid credit does not expire at this timestamp.
              required: true
              schema:
                type: string
                format: date-time
            X-Balance-Cents:
              description: Compatibility alias of X-Remaining-Cents.
              required: true
              schema:
                type: integer
                minimum: 0
            X-Rate-Card-Version:
              description: Version of the endpoint rate card used for this call.
              required: true
              schema:
                type: integer
                minimum: 1
            X-Request-Id:
              description: Request identifier to quote in support requests.
              required: true
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              example:
                detail:
                - type: missing
                  loc:
                  - query
                  - address
                  msg: Field required
                  input: null
      x-price-cents: 23
components:
  schemas:
    BasicsAll:
      properties:
        bed_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bed Count
          description: Bedrooms as advertised. Null = unknown, not zero.
        bath_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bath Count
          description: Bathrooms as advertised, whole number. Null = unknown, not zero.
        parking_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Parking Count
          description: Covered car spaces (garage/carport) as advertised — excludes open driveway and street parking. Null = unknown.
        dwelling_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Dwelling Type
          description: Dwelling kind in lowercase free text ('house', 'unit', 'townhouse', …), from the listing or the national address file. Not a closed set.
        land_area_sqm:
          anyOf:
          - type: number
          - type: 'null'
          title: Land Area Sqm
          description: Advertised land size in square metres (hectares converted for you), indicative rather than surveyed. Null = not stated; usual for units.
      type: object
      title: BasicsAll
      description: 'All property basics — beds, baths, parking, dwelling type, land area —

        in one call.


        Every one of these comes from what the property was advertised with, so

        a null is "never advertised" rather than "zero", and a property that has

        never been listed comes back with all five null. Values are returned

        flat here (no per-field wrapper object, unlike the individual endpoints).'
      example:
        bath_count: 2
        bed_count: 4
        dwelling_type: house
        land_area_sqm: 814.0
        parking_count: 5
    ApiResponse_BasicsAll_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/BasicsAll'
          - type: 'null'
          description: The endpoint's payload, or `null` when Microburbs has no value.
        available:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Available
          description: '`false` on no-data responses. Omitted on success — branch on `data !== null` if you want a single discriminator.'
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Machine-readable slug naming the no-data condition (e.g. `no_avm_for_GANSW704074813`). Stable per endpoint. Omitted on success.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Human-readable explanation. Omitted on success.
      type: object
      title: ApiResponse[BasicsAll]
    ApiResponse_BedCount_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/BedCount'
          - type: 'null'
          description: The endpoint's payload, or `null` when Microburbs has no value.
        available:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Available
          description: '`false` on no-data responses. Omitted on success — branch on `data !== null` if you want a single discriminator.'
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Machine-readable slug naming the no-data condition (e.g. `no_avm_for_GANSW704074813`). Stable per endpoint. Omitted on success.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Human-readable explanation. Omitted on success.
      type: object
      title: ApiResponse[BedCount]
    ApiResponse_BathCount_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/BathCount'
          - type: 'null'
          description: The endpoint's payload, or `null` when Microburbs has no value.
        available:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Available
          description: '`false` on no-data responses. Omitted on success — branch on `data !== null` if you want a single discriminator.'
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Machine-readable slug naming the no-data condition (e.g. `no_avm_for_GANSW704074813`). Stable per endpoint. Omitted on success.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Human-readable explanation. Omitted on success.
      type: object
      title: ApiResponse[BathCount]
    LandAreaSqm:
      properties:
        land_area_sqm:
          anyOf:
          - type: number
          - type: 'null'
          title: Land Area Sqm
          description: Land size in square metres — the figure the property was advertised with, not a survey or cadastral parcel measurement, so treat it as indicative. Acreage advertised in hectares is converted to square metres for you (1 ha = 10,000 sqm), which means small values are rare by construction and a suspiciously round large number may be a converted one. Null means no listing stated a land size; expect that on most apartments and units.
      type: object
      required:
      - land_area_sqm
      title: LandAreaSqm
      example:
        land_area_sqm: 814.0
    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
    BedCount:
      properties:
        bed_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bed Count
          description: Bedrooms, as advertised when the property was last on the market. Null means no listing on record ever stated one — read it as unknown, never as zero.
      type: object
      required:
      - bed_count
      title: BedCount
      example:
        bed_count: 4
    ApiResponse_LandAreaSqm_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/LandAreaSqm'
          - type: 'null'
          description: The endpoint's payload, or `null` when Microburbs has no value.
        available:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Available
          description: '`false` on no-data responses. Omitted on success — branch on `data !== null` if you want a single discriminator.'
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Machine-readable slug naming the no-data condition (e.g. `no_avm_for_GANSW704074813`). Stable per endpoint. Omitted on success.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Human-readable explanation. Omitted on success.
      type: object
      title: ApiResponse[LandAreaSqm]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BathCount:
      properties:
        bath_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bath Count
          description: Bathrooms, as advertised when the property was last on the market. Whole number — half-bathrooms and powder rooms are not represented. Null means unknown, not zero.
      type: object
      required:
      - bath_count
      title: BathCount
      example:
        bath_count: 2
    DwellingType:
      properties:
        dwelling_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Dwelling Type
          description: 'What kind of dwelling it is — lowercase free text such as ''house'', ''unit'', ''townhouse'', ''apartment''. Taken from the advertised listing type, falling back to the national address file''s classification when no listing states one. Not a closed set: match case-insensitively and allow for values outside the common few.'
      type: object
      required:
      - dwelling_type
      title: DwellingType
      example:
        dwelling_type: house
    ApiResponse_ParkingCount_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/ParkingCount'
          - type: 'null'
          description: The endpoint's payload, or `null` when Microburbs has no value.
        available:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Available
          description: '`false` on no-data responses. Omitted on success — branch on `data !== null` if you want a single discriminator.'
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Machine-readable slug naming the no-data condition (e.g. `no_avm_for_GANSW704074813`). Stable per endpoint. Omitted on success.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Human-readable explanation. Omitted on success.
      type: object
      title: ApiResponse[ParkingCount]
    ApiResponse_DwellingType_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/DwellingType'
          - type: 'null'
          description: The endpoint's payload, or `null` when Microburbs has no value.
        available:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Available
          description: '`false` on no-data responses. Omitted on success — branch on `data !== null` if you want a single discriminator.'
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Machine-readable slug naming the no-data condition (e.g. `no_avm_for_GANSW704074813`). Stable per endpoint. Omitted on success.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Human-readable explanation. Omitted on success.
      type: object
      title: ApiResponse[DwellingType]
    ParkingCount:
      properties:
        parking_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Parking Count
          description: Covered car spaces (garage/carport) as advertised. It does not count open driveway or street parking, so a house with a wide driveway and no garage can legitimately read 0 or null. Null means unknown.
      type: object
      required:
      - parking_count
      title: ParkingCount
      example:
        parking_count: 5
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key as Bearer token. Use `test` for the public sandbox (works only for GNAFs GANSW704074813, GAACT714845944, GAVIC419929404, GAQLD162849753, GAWA_146662014, GASA_422266490, GATAS702292990, GANT_703835649 and SALs 'Belmont North', 'Bondi', 'St Kilda (Vic.)', 'Fortitude Valley', 'Subiaco', 'Unley', 'Sandy Bay', 'Kambah', 'Nightcliff', always 0¢). Mint your own at /developers/keys for full access.
x-tagGroups:
- name: Suburb
  tags:
  - Suburb - Hero
  - Suburb - Profile
  - Suburb - Market
  - Suburb - Forecast
  - Suburb - Listings
  - Suburb - Sales
  - Suburb - Street Forecasts
  - Suburb - Demographics
  - Suburb - Ethnicity
  - Suburb - Development
  - Suburb - Schools
  - Suburb - Risks
  - Suburb - Crime
  - Suburb - Lifestyle
  - Suburb - Similar
  - Suburb - Shapes
- name: Finders
  tags:
  - Suburb - Finder
- name: Property
  tags:
  - Property - Profile
  - Property - Basics
  - Property - Valuation
  - Property - History
  - Property - Title
  - Property - Comparables
  - Property - Development
  - Property - Schools
  - Property - Amenities
  - Property - Risks
  - Property - Surroundings
  - Property - Context
- name: Area Statistics
  tags:
  - Area Statistics
- name: Mesh Block
  tags:
  - Mesh Block - Profile
- name: LGA
  tags:
  - LGA - Profile
- name: SA4
  tags:
  - SA4 - Profile
- name: Geocode
  tags:
  - Geocode
- name: Account
  tags:
  - Account