PropertyIndex Account API

openapi: 3.2.0
info:
  title: PIX Account API
  version: 1.0.0
  description: 'The PIX API gives licensed organisations direct, programmatic access to the

    Dubai Land Department records that PropertyIndex models: every registered

    sale, every registered tenancy period, its location labels and floor,

    and the PIX market index, as flat rows you can pull into your

    own systems. Each record carries its registered figures and our per-record

    calculations (price and rent per square foot, normalised property type and

    bedrooms). Location and floor labels are not identifiers or proof of a

    unique physical structure. Unit numbers, persistent property identities and cross-record histories are

    not part of the API. ## Location labels


    Sales and rentals carry the record''s assigned location as labels:


    - `location_path` is the full published path, an ordered list of labels

    from Dubai to the assigned location. - `highest_location_level` is the first node after Dubai, regardless of

    its kind. - `lowest_location_level` is the final assigned location node, which

    may be an area, community, subcommunity, tower or the city itself. For a sale in Beach Vista Tower 1:


    ```json

    {

    "location_path": ["Dubai", "Dubai Harbour", "Emaar Beachfront", "Beach Vista", "Beach Vista Tower 1"],

    "highest_location_level": "Dubai Harbour",

    "lowest_location_level": "Beach Vista Tower 1"

    }

    ```


    When only one node follows Dubai, both level fields contain that node''s

    label. For a city-only assignment, the path is `["Dubai"]`, the highest

    value is null and the lowest is `Dubai`. All three are null when the

    location is unresolved; a path is never partial. Labels are names, not identifiers, and names can repeat across the tree. `location_path` is returned by default and can be requested with

    `fields`, but it is not a filter, sort or cursor field. To scope a query

    to a place, use `location_id`. ## Base URL


    All endpoints are served from `https://api.propertyindex.ae`. Only `GET`

    requests are accepted. Responses are JSON. ## Authentication


    Send your key as a bearer token on every request:


    ```

    Authorization: Bearer pix_api_XXXXXXXXXX_... ```


    Keys are issued to your organisation, not to a person. Keep them server-side. A key can be revoked and reissued at any time on request. ## Allowance and rate limits


    Authenticated responses carry your meter in headers: `PIX-Usage-Used`,

    `PIX-Usage-Allowance`, `PIX-Usage-Remaining`, `PIX-Usage-Period` and,

    where the period has an end, `PIX-Usage-Period-End`. `PIX-Usage-Unit: records` identifies the unit. `PIX-Usage-Remaining`

    means included records remaining, excluding optional overage capacity. `GET /v1/usage` returns these figures and the effective

    `recordsRemaining`, including any enabled overage capacity, without

    consuming records. The paid plan is AED 5,000 per month and includes 1,000,000 sales and rental

    records per billing period, shared across the organisation''s API keys. Each actual row returned by a sales or rentals

    list counts as one record; a successful single-record response counts as

    one. Repeated retrievals count again. Query and validation failures and

    empty responses consume no records. Locations, market index, documentation

    and usage are unmetered. Optional overage costs AED 2 per 1,000 records, prorated to the nearest fils

    on the billing period total: `overageCostMinor = round(overageRecords / 5)`. Overage is off by default. An organisation owner or admin must opt in and

    set a finite monthly overage spending cap, excluding the subscription and

    any applicable taxes. `overageCapMinor` is that cap

    in fils; when enabled, each fils adds five records to `recordLimit` above

    the included allowance. `remaining` counts only unused included records;

    `recordsRemaining` counts capacity up to the effective `recordLimit`. Demo grants have a fixed record allowance with no overage. Both demo and paid keys enforce a hard limit. If the actual response would

    exceed `recordsRemaining`, the whole response is rejected with

    `429 allowance_exhausted` and no records are charged.'
  contact:
    name: PropertyIndex
    email: info@propertyindex.ae
    url: https://www.propertyindex.ae
  termsOfService: https://www.propertyindex.ae/terms-of-service
  license:
    name: PIX API licence (proprietary)
    url: https://www.propertyindex.ae/terms-of-service
servers:
- url: https://api.propertyindex.ae
security:
- bearerAuth: []
tags:
- name: Account
  description: Your key's allowance and usage.
paths:
  /v1/usage:
    get:
      tags:
      - Account
      operationId: getUsage
      summary: Current allowance and usage
      description: 'Unmetered: consumes no records. The burst rate limit still applies.'
      responses:
        '200':
          description: Usage for the key's current period.
          headers:
            PIX-Usage-Kind:
              description: paid or demo.
              schema:
                type: string
                enum:
                - paid
                - demo
            PIX-Usage-Unit:
              description: The usage unit is records.
              schema:
                type: string
                const: records
            PIX-Usage-Used:
              description: Sales and rental records used in the current period, including this response.
              schema:
                type: integer
                minimum: 0
            PIX-Usage-Allowance:
              description: Records included in the current period, before optional overage.
              schema:
                type: integer
                minimum: 0
            PIX-Usage-Remaining:
              description: Included records remaining, excluding overage capacity. GET /v1/usage returns recordsRemaining for effective capacity.
              schema:
                type: integer
                minimum: 0
            PIX-Usage-Period:
              description: Identifier of the current period.
              schema:
                type: string
            PIX-Usage-Period-End:
              description: When the current period ends, if it does.
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Usage'
        '401':
          description: Missing or unrecognised API key.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The key is not active, or the organisation holds no licence or demo allowance.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit reached, or the response exceeds recordsRemaining (allowance_exhausted). The whole response is rejected without consuming records; request a smaller limit if capacity remains.
          headers:
            PIX-Usage-Kind:
              description: paid or demo.
              schema:
                type: string
                enum:
                - paid
                - demo
            PIX-Usage-Unit:
              description: The usage unit is records.
              schema:
                type: string
                const: records
            PIX-Usage-Used:
              description: Sales and rental records used in the current period, including this response.
              schema:
                type: integer
                minimum: 0
            PIX-Usage-Allowance:
              description: Records included in the current period, before optional overage.
              schema:
                type: integer
                minimum: 0
            PIX-Usage-Remaining:
              description: Included records remaining, excluding overage capacity. GET /v1/usage returns recordsRemaining for effective capacity.
              schema:
                type: integer
                minimum: 0
            PIX-Usage-Period:
              description: Identifier of the current period.
              schema:
                type: string
            PIX-Usage-Period-End:
              description: When the current period ends, if it does.
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds to wait before retrying (rate limit only).
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Usage:
      type: object
      required:
      - kind
      - unit
      - used
      - allowance
      - remaining
      - hardCap
      - periodKey
      - periodEnd
      - overageEnabled
      - overageCapMinor
      - overageRecords
      - overageCostMinor
      - recordLimit
      - recordsRemaining
      properties:
        kind:
          type: string
          enum:
          - paid
          - demo
        unit:
          type: string
          const: records
        used:
          type: integer
          minimum: 0
          description: Sales and rental records returned in this period. Repeated retrievals count again.
        allowance:
          type: integer
          minimum: 0
          description: 'Included records: 1,000,000 per paid billing period, or the fixed demo grant.'
        remaining:
          type: integer
          minimum: 0
          description: 'Included records remaining: max(0, allowance - used). Excludes overage capacity.'
        hardCap:
          type: boolean
          const: true
          description: Always true. A response exceeding recordsRemaining is rejected in full without consuming records.
        periodKey:
          type: string
        periodEnd:
          type:
          - string
          - 'null'
          format: date-time
        overageEnabled:
          type: boolean
          description: Off by default. Requires paid-plan owner/admin opt-in and a finite monthly overage spending cap. Demos do not support overage.
        overageCapMinor:
          type: integer
          minimum: 0
          description: Monthly overage spending cap in fils (100 fils = AED 1).
        overageRecords:
          type: integer
          minimum: 0
          description: 'Records above the included allowance: max(0, used - allowance).'
        overageCostMinor:
          type: integer
          minimum: 0
          description: 'Overage cost in fils, rounded on the billing period total: round(overageRecords / 5). Equivalent to AED 2 per 1,000 records.'
        recordLimit:
          type: integer
          minimum: 0
          description: 'Effective record limit: allowance + (overageEnabled ? overageCapMinor * 5 : 0).'
        recordsRemaining:
          type: integer
          minimum: 0
          description: 'Effective records remaining, including enabled overage capacity: max(0, recordLimit - used).'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              example: invalid_parameter
            message:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your PIX API key, sent as `Authorization: Bearer pix_api_...`.'