REA Group Auction Results API

openapi: 3.2.0
info:
  version: v2
  title: Market Auction Results API
  description: '- **Market/Auctions: GET /api/v2/market/auctions**

    Retrieves auction result statistics for a given state, suburb or greater capital city statistical area

    - **Market/Rent History: GET /api/v2/market/rent/historic/{metric}**

    Retrieves historic rental transaction statistics for a given suburb

    - **Market/Sale History: GET /api/v2/market/sale/historic/{metric}**

    Retrieves historic sale transaction statistics for a given suburb


    - **Market/Supply & Demand: GET…'
  termsOfService: https://developer.proptrack.com.au/docs/apis/terms-of-use
  contact:
    name: PropTrack
    url: https://www.proptrack.com.au/contact-us
    email: https://www.proptrack.com.au/contact-us
servers:
- url: https://data.proptrack.com
tags:
- name: Auction Results
paths:
  /api/v2/market/auctions:
    get:
      tags:
      - Auction Results
      summary: /api/v2/market/auctions
      description: Retrieves auction result statistics for a given state, suburb or greater capital city statistical area.
      operationId: get-api-v2-market-auctions
      parameters:
      - name: Authorization
        in: header
        description: Provide your bearer token as a string, in the format `Bearer {access_token}` in the Authorization Header</br>Refer to [Authentication](https://developer.proptrack.com.au/docs/apis/authentication/operations/create-a-oauth-2-token)
        required: true
        schema:
          type: string
          examples:
          - Bearer jyJraWQiOiJiYWRmKzUyNC1jYzBkLTQ9YWUtYTAzMC02MjBlYTE3ZDNlZjMiLCJ0eXAiO
          default: Bearer {access_token}
          example: Bearer jyJraWQiOiJiYWRmKzUyNC1jYzBkLTQ9YWUtYTAzMC02MjBlYTE3ZDNlZjMiLCJ0eXAiO
      - name: searchType
        in: query
        description: Defines the identifier used</br>Refer to [Search Type Values](https://developer.proptrack.com.au/docs/apis/guide#valid-market-search-types)
        required: true
        schema:
          enum:
          - suburb
          - state
          - gccsa
          type: string
      - name: suburb
        in: query
        description: 'Suburb name</br>Note: If `searchType` equals `suburb`, then this field is <span style="color:#F47853">required</span>'
        schema:
          type: string
          examples:
          - Berwick
      - name: state
        in: query
        description: 'State or territory within Australia</br>Note: If `searchType` equals `suburb` or `state`, then this field is <span style="color:#F47853">required</span>'
        schema:
          enum:
          - act
          - nsw
          - nt
          - qld
          - sa
          - tas
          - vic
          - wa
          examples:
          - vic
          type: string
      - name: postcode
        in: query
        description: 'Four digit postcode</br>Note: If `searchType` equals `suburb`, then this field is <span style="color:#F47853">required</span>'
        schema:
          type: number
          examples:
          - 3806
      - name: gccsaCode
        in: query
        description: 'Greater Capital City Statistical Area (GCCSA) code</br>Note: If `searchType` equals `gccsa`, then this field is <span style="color:#F47853">required</span>'
        schema:
          type: string
          examples:
          - 2GMEL
      - name: startDate
        in: query
        description: Start of date range to be queried. Defaulted to 4 weeks prior to today's date if left empty</br>Format `YYYY-MM-DD`
        schema:
          type: string
          examples:
          - '2023-08-01'
      - name: endDate
        in: query
        description: End of date range to be queried. Defaulted to today's date if left empty</br>Format `YYYY-MM-DD`
        schema:
          type: string
          examples:
          - '2023-09-30'
      responses:
        '200':
          description: '<!-- theme: success -->


            > #### Success (200)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  dateRanges:
                    type: array
                    description: Time period which the metric is expressed across
                    items:
                      type: object
                      properties:
                        startDate:
                          type: string
                          description: 'First date in the date range</br>

                            Format `YYYY-MM-DD`'
                          examples:
                          - '2023-10-02'
                        endDate:
                          type: string
                          description: 'Final date in the date range</br>

                            Format `YYYY-MM-DD`'
                          examples:
                          - '2023-10-08'
                        metricValues:
                          type: object
                          properties:
                            clearanceRate:
                              type: object
                              description: The percentage of properties that were sold during the date range (including those sold before and after auction) out of the total number of auctions
                              properties:
                                value:
                                  type: number
                                  description: The clearance rate for the given date range, expressed as a percentage
                                  format: float
                                  examples:
                                  - 63.7344
                                changePercentage:
                                  type: number
                                  description: The difference between clearance rate for a given date range and the previous date range, expressed by percentage
                                  examples:
                                  - 10.13
                                observations:
                                  type: integer
                                  description: The number of properties/auctions observed to calculate the clearance rate
                                  examples:
                                  - 1205
                            countScheduled:
                              type: object
                              description: The number of properties that were scheduled for auction during the date range
                              properties:
                                value:
                                  type: integer
                                  description: The scheduled auction count for the given date range
                                  examples:
                                  - 62
                                changePercentage:
                                  type: number
                                  description: The difference between the count for a given date range and the previous date range, expressed by percentage
                                  examples:
                                  - 31.33
                            countSold:
                              type: object
                              description: The number of properties that were sold at auction during the date range
                              properties:
                                value:
                                  type: integer
                                  description: The sold auction count for the given date range
                                  examples:
                                  - 523
                                changePercentage:
                                  type: number
                                  description: The difference between the count for a given date range and the previous date range, expressed by percentage
                                  examples:
                                  - 42.37
                            countSoldPrior:
                              type: object
                              description: The number of properties that were sold prior to the scheduled auction during the date range
                              properties:
                                value:
                                  type: integer
                                  description: The number of properties that were sold prior to the scheduled auction during the date range
                                  examples:
                                  - 205
                                changePercentage:
                                  type: number
                                  description: The difference between the count for a given date range and the previous date range, expressed by percentage
                                  examples:
                                  - 62.14
                            countSoldAfter:
                              type: object
                              description: The number of properties that were sold after the scheduled auction during the date range
                              properties:
                                value:
                                  type: integer
                                  description: The sold after auction count for the given date range
                                  examples:
                                  - 40
                                changePercentage:
                                  type: number
                                  description: The difference between the count for a given date range and the previous date range, expressed by percentage
                                  examples:
                                  - -16.67
                            countPassedIn:
                              type: object
                              description: The number of properties that were passed in auction during the date range
                              properties:
                                value:
                                  type: integer
                                  description: The passed in auction count for the given date range
                                  examples:
                                  - 303
                                changePercentage:
                                  type: number
                                  description: The difference between the count for a given date range and the previous date range, expressed by percentage
                                  examples:
                                  - 3.72
                            countWithdrawn:
                              type: object
                              description: The number of properties that were withdrawn from auction during the date range
                              properties:
                                value:
                                  type: integer
                                  description: The withdrawn auction count for the given date range
                                  examples:
                                  - 134
                                changePercentage:
                                  type: number
                                  description: The difference between the count for a given date range and the previous date range, expressed by percentage
                                  examples:
                                  - 22.63
                x-examples:
                  Example 1:
                    dateRanges:
                    - startDate: '2023-10-02'
                      endDate: '2023-10-08'
                      metricValues:
                        clearanceRate:
                          value: 63.7344
                          changePercentage: 10.13
                          observations: 1205
                        countScheduled:
                          value: 62
                          changePercentage: 313.33
                        countSold:
                          value: 523
                          changePercentage: 462.37
                        countSoldPrior:
                          value: 205
                          changePercentage: 632.14
                        countSoldAfter:
                          value: 40
                          changePercentage: 166.67
                        countPassedIn:
                          value: 303
                          changePercentage: 396.72
                        countWithdrawn:
                          value: 134
                          changePercentage: 252.63
                    - startDate: '2023-10-09'
                      endDate: '2023-10-15'
                      metricValues:
                        clearanceRate:
                          value: 60.3704
                          changePercentage: -5.28
                          observations: 1080
                        countScheduled:
                          value: 51
                          changePercentage: -17.74
                        countSold:
                          value: 479
                          changePercentage: -8.41
                        countSoldPrior:
                          value: 149
                          changePercentage: -27.32
                        countSoldAfter:
                          value: 24
                          changePercentage: -40
                        countPassedIn:
                          value: 299
                          changePercentage: -1.32
                        countWithdrawn:
                          value: 129
                          changePercentage: -3.73
              examples:
                Two Weeks of Auction Results:
                  value:
                    dateRanges:
                    - startDate: '2023-10-02'
                      endDate: '2023-10-08'
                      metricValues:
                        clearanceRate:
                          value: 63.7344
                          changePercentage: 10.13
                          observations: 1205
                        countScheduled:
                          value: 62
                          changePercentage: 313.33
                        countSold:
                          value: 523
                          changePercentage: 462.37
                        countSoldPrior:
                          value: 205
                          changePercentage: 632.14
                        countSoldAfter:
                          value: 40
                          changePercentage: 166.67
                        countPassedIn:
                          value: 303
                          changePercentage: 396.72
                        countWithdrawn:
                          value: 134
                          changePercentage: 252.63
                    - startDate: '2023-10-09'
                      endDate: '2023-10-15'
                      metricValues:
                        clearanceRate:
                          value: 60.3704
                          changePercentage: -5.28
                          observations: 1080
                        countScheduled:
                          value: 51
                          changePercentage: -17.74
                        countSold:
                          value: 479
                          changePercentage: -8.41
                        countSoldPrior:
                          value: 149
                          changePercentage: -27.32
                        countSoldAfter:
                          value: 24
                          changePercentage: -40
                        countPassedIn:
                          value: 299
                          changePercentage: -1.32
                        countWithdrawn:
                          value: 129
                          changePercentage: -3.73
        '400':
          description: '<!-- theme: danger -->


            > #### Bad Request (400)'
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    errors:
                    - code: 7004
                      level: CRITICAL
                      description: Required parameter is missing - Please ensure that all required parameters have been included
                      parameters:
                        searchType: is a required parameter
                        state: is a required parameter
                        postcode: is a required parameter
                        suburb: is a required parameter
                        gccsaCode: is a required parameter
                        startDate: is a required parameter
                        endDate: is a required parameter
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          description: Defines the type of error that has occurred
                          enum:
                          - 7004
                          - 7005
                          - 7007
                          - 7008
                          - 7010
                          - 7011
                          - 7014
                          - 7015
                        description:
                          type: string
                          description: Overview of the error that has occurred
                          example: Required parameter is missing - Please ensure that all required parameters have been included
                        parameters:
                          type: object
                          description: A set of parameters that are causing the error and the rule that was invoked
                          properties:
                            searchType:
                              type: string
                              example: is a required parameter
                            state:
                              type: string
                              example: must only include an allowed value
                            postcode:
                              type: string
                              example: must be an integer
                            suburb:
                              type: string
                              example: is a required parameter when searching by suburb
                            gccsaCode:
                              type: string
                              example: is a required parameter when searching by gccsa
                            startDate:
                              type: string
                              example: must be in ISO_8601 format (YYYY-MM-DD)
                            endDate:
                              type: string
                              example: must be in ISO_8601 format (YYYY-MM-DD)
                      required:
                      - code
                      - description
              examples:
                7004 - Required Parameter Missing:
                  value:
                    errors:
                    - code: 7004
                      description: Required parameter is missing - Please ensure that all required parameters have been included
                      parameters:
                        searchType: is a required parameter
                        state: is a required parameter when searching by state or suburb
                        postcode: is a required parameter when searching by suburb
                        suburb: is a required parameter when searching by suburb
                        gccsaCode: is a required parameter when searching by gccsa
                7005 - Invalid Value Entry:
                  value:
                    errors:
                    - code: 7005
                      description: Invalid value entry - Please ensure that all values entered are valid
                      parameters:
                        startDate: is not a valid date
                        endDate: is not a valid date
                7007 - Non-Allowed Value in Enum Field:
                  value:
                    errors:
                    - code: 7007
                      description: A non-allowed value has been included into an enum field - Please ensure that the value entered is an allowed option
                      parameters:
                        searchType: must only include an allowed value
                        state: must only include an allowed value
                7008 - Incorrect Field Type:
                  value:
                    errors:
                    - code: 7008
                      description: An incorrect field type has been included - Please ensure that all values are using the correct field type
                      parameters:
                        postcode: must be an integer
                7010 - Incorrect Format:
                  value:
                    errors:
                    - code: 7010
                      description: An incorrect format has been included - Please ensure that the correct formatting has been used for all parameters
                      parameters:
                        startDate: must be in ISO_8601 format (YYYY-MM-DD)
                        endDate: must be in ISO_8601 format (YYYY-MM-DD)
                7011 - Above/Below Limit:
                  value:
                    errors:
                    - code: 7011
                      description: A value above/below the allowed limit has been included - Please ensure that a valid value has been entered
                      parameters:
                        postcode: must not exceed 4 digits
                7014 - Invalid Date Range:
                  value:
                    errors:
                    - code: 7014
                      description: An invalid date range has been included - Please ensure that the start and end dates are valid
                      parameters:
                        startDate: cannot exceed the current date
                        endDate: cannot exceed the current date
                7015 - Conflicting Date Range:
                  value:
                    errors:
                    - code: 7015
                      description: A conflicting date range has been included - Please ensure that the start and end dates are compatible
                      parameters:
                        startDate: cannot be set as a date after endDate
        '401':
          description: '<!-- theme: danger -->


            > #### Unauthorized (401)'
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    errors:
                    - code: 9012
                      level: CRITICAL
                      description: Authentication token validation has failed - Please ensure that a valid token authentication request has been completed before trying again
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          description: Defines the type of error that has occurred
                          enum:
                          - 9012
                          - 9016
                        level:
                          description: 'Defines the severity of the error</br>Note: If level is `CRITICAL` then a successful response will not be returned'
                          deprecated: true
                          enum:
                          - CRITICAL
                        description:
                          type: string
                          description: Overview of the error that has occurred
                          example: Authentication token validation has failed - Please ensure that a valid token authentication request has been completed before trying again
                      required:
                      - code
                      - description
              examples:
                9012 - Invalid Auth Token:
                  value:
                    errors:
                    - code: 9012
                      level: CRITICAL
                      description: Authentication token validation has failed - Please ensure that a valid token authentication request has been completed before trying again
                9016 - Expired Auth Token:
                  value:
                    errors:
                    - code: 9016
                      level: CRITICAL
                      description: Authentication token has expired - Please ensure that a valid token authentication request has been completed before trying again
        '403':
          description: '<!-- theme: danger -->


            > #### Forbidden (403)'
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    errors:
                    - code: 9003
                      description: Access denied - Please contact our customer support team at support@proptrack.com for access to this endpoint
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          description: Defines the type of error that has occurred
                          enum:
                          - 9003
                        description:
                          type: string
                          description: Overview of the error that has occurred
                          example: Access denied - Please contact our customer support team at support@proptrack.com for access to this endpoint
                      required:
                      - code
                      - description
              examples:
                9003 - Access Denied:
                  value:
                    errors:
                    - code: 9003
                      description: Access denied - Please contact our customer support team at support@proptrack.com for access to this endpoint
        '404':
          description: '<!-- theme: danger -->


            > #### Not Found (404)'
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    errors:
                    - code: 7002
                      level: CRITICAL
                      description: Unknown identifier, the included address does not match a record within our system - Please ensure that the state, suburb and postcode are correct
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          enum:
                          - 7002
                          description: Defines the type of error that has occurred
                        description:
                          type: string
                          example: Unknown identifier, the included location does not match a record within our system - Please ensure that the identifier is correct
                          description: Overview of the error that has occurred
                        parameters:
                          type: object
                          x-stoplight:
                            id: fwibzr5ow9gcz
                          description: A set of parameters that are causing the error and the rule that was invoked
                          properties:
                            gccsa:
                              type: string
                              x-stoplight:
                                id: qs3j3puelq6dc
                              example: cannot be found
                            suburb:
                              type: string
                              x-stoplight:
                                id: ujm1ijk0s1qj4
                              example: cannot be found
                      required:
                      - code
                      - description
              examples:
                7002 - Unknown Identifier:
                  value:
                    errors:
                    - code: 7002
                      description: Unknown identifier, the included location does not match a record within our system - Please ensure that the identifier is correct
                      parameters:
                        suburb: cannot be found
        '429':
          description: '<!-- theme: danger -->


            > #### Too Many Requests (429)'
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    errors:
                    - code: 9011
                      level: CRITICAL
                      description: Rate limit has been exceeded - Please try again shortly
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          enum:
                          - 9011
                          description: Defines the type of error that has occurred
                        level:
                          deprecated: true
                          enum:
                          - CRITICAL
                          description: 'Defines the severity of the error</br>Note: If level is `CRITICAL` then a successful response will not be returned'
                        description:
                          type: string
                          example: Rate limit has been exceeded - Please try again shortly
                          description: Overview of the error that has occurred
                      required:
                      - code
                      - description
              examples:
                9011- Rate Limit Exceeded:
                  value:
                    errors:
                    - code: 9011
                      level: CRITICAL
                      description: Rate limit has been exceeded - Please try again shortly
                9011 - Quota Limit Exceeded:
                  value:
                    errors:
                    - code: 9011
                      level: CRITICAL
                      description: Quota limit has been reached - Please contact our customer support team at support@proptrack.com for further information
        '500':
          description: '<!-- theme: danger -->


            > #### Internal Server Error (500)'
      servers:
      - url: https://data.proptrack.com
      x-stoplight:
        id: df1d5fvuid3k9