> ## Documentation Index
> Fetch the complete documentation index at: https://developers.apartmentiq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Suggest Comps

> Rank comp candidates for a subject property, scored the way ApartmentIQ scores comps when it suggests them for a comp set, without value-add.

- Candidates come from the 1,500 properties with the most units within 25 miles that are active or have floorplan-only data. Properties with known occupancy data issues are removed after that cap, so the pool can be smaller.
- For a subject that is not conventional, candidates must have exactly the same property type. For a conventional subject, candidates of every type are included and the score decides: under comp scoring V1 a different type scores 0, and under V2 only senior living candidates are removed.
- Filters run on that pool after the 1,500 cap. In a dense market, a narrow filter can return few or no suggestions even when matching properties exist nearby. Range and class filters drop candidates whose value is unknown.
- At most half of `limit`, rounded down, can be lease-ups, so `limit=1` never returns a lease-up. When the subject is leasing up, lease-ups come first.
- Scores run from 0 to 1 under both comp scoring versions, but they mean different things, so compare scores only within one account.
- With the default `minimum_score` of 0.5, a request can return fewer than `limit` suggestions. Under V2, 0.5 is a strict cutoff. Lower `minimum_score` for a longer list. Under V2, deactivated candidates score 0, and a deactivated subject gets no suggestions.
- With `comp_set_id`, suggestions that are comps in that comp set have `in_comp_set: true` and count toward `limit`. A comp in the set appears only if it passes every rule above. The comp set's exclusions are not applied.

This request scores candidates live, so it can take several seconds in dense markets.



## OpenAPI

````yaml /openapi/v2/schema.json get /properties/{property_id}/comp_suggestions
openapi: 3.1.0
info:
  title: ApartmentIQ API V2
  version: 2.7.2
  termsOfService: https://www.getapartmentiq.com/terms
  x-logo:
    url: https://developers.apartmentiq.io/logo.svg
    altText: ApartmentIQ
  description: >-
    ApartmentIQ API V2 endpoints for account discovery, search, organization
    details, bulk Explore data, dataset downloads, and market survey and
    research report creation.
servers:
  - url: https://data.apartmentiq.io/apartmentiq/api/v2
security:
  - bearerAuth: []
tags:
  - name: Accounts
    description: Account discovery endpoints.
  - name: Amenities
    description: Amenity discovery endpoints.
  - name: Properties
    description: Property search endpoints.
  - name: Markets
    description: Market and geo-boundary search endpoints.
  - name: Organizations
    description: Organization search endpoints.
  - name: Datasets
    description: Complete dataset snapshot downloads.
  - name: Bulk
    description: Bulk property, market, organization, quota, and forecast exports.
  - name: Market Surveys
    description: >-
      Comp suggestions, market survey and research report creation, and comp set
      edits.
paths:
  /properties/{property_id}/comp_suggestions:
    get:
      tags:
        - Market Surveys
      summary: Suggest Comps
      description: >-
        Rank comp candidates for a subject property, scored the way ApartmentIQ
        scores comps when it suggests them for a comp set, without value-add.


        - Candidates come from the 1,500 properties with the most units within
        25 miles that are active or have floorplan-only data. Properties with
        known occupancy data issues are removed after that cap, so the pool can
        be smaller.

        - For a subject that is not conventional, candidates must have exactly
        the same property type. For a conventional subject, candidates of every
        type are included and the score decides: under comp scoring V1 a
        different type scores 0, and under V2 only senior living candidates are
        removed.

        - Filters run on that pool after the 1,500 cap. In a dense market, a
        narrow filter can return few or no suggestions even when matching
        properties exist nearby. Range and class filters drop candidates whose
        value is unknown.

        - At most half of `limit`, rounded down, can be lease-ups, so `limit=1`
        never returns a lease-up. When the subject is leasing up, lease-ups come
        first.

        - Scores run from 0 to 1 under both comp scoring versions, but they mean
        different things, so compare scores only within one account.

        - With the default `minimum_score` of 0.5, a request can return fewer
        than `limit` suggestions. Under V2, 0.5 is a strict cutoff. Lower
        `minimum_score` for a longer list. Under V2, deactivated candidates
        score 0, and a deactivated subject gets no suggestions.

        - With `comp_set_id`, suggestions that are comps in that comp set have
        `in_comp_set: true` and count toward `limit`. A comp in the set appears
        only if it passes every rule above. The comp set's exclusions are not
        applied.


        This request scores candidates live, so it can take several seconds in
        dense markets.
      operationId: suggestV2Comps
      parameters:
        - name: property_id
          in: path
          required: true
          schema:
            type: integer
          description: ApartmentIQ property ID of the subject property.
        - name: account_id
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 25
          description: Maximum number of suggestions.
        - name: minimum_score
          in: query
          required: false
          schema:
            type: number
            minimum: 0
            default: 0.5
          description: Lowest score to include.
        - name: comp_set_id
          in: query
          required: false
          schema:
            type: integer
          description: >-
            An active comp set in the account that the user can open. Its comps
            are flagged with in_comp_set.
        - name: year_built_gte
          in: query
          required: false
          schema:
            type: integer
        - name: year_built_lte
          in: query
          required: false
          schema:
            type: integer
        - name: total_units_gte
          in: query
          required: false
          schema:
            type: integer
        - name: total_units_lte
          in: query
          required: false
          schema:
            type: integer
        - name: number_of_stories_gte
          in: query
          required: false
          schema:
            type: integer
        - name: number_of_stories_lte
          in: query
          required: false
          schema:
            type: integer
        - name: property_class
          in: query
          required: false
          schema:
            type: string
          description: 'Comma-separated property classes: A, B, C, D. Uppercase only.'
        - name: property_type
          in: query
          required: false
          schema:
            type: string
          description: >-
            Comma-separated property types: conventional, student (or
            student_housing), senior (or senior_living), build_to_rent,
            affordable. Not case-sensitive. The list must include the subject
            property's own type. Suggestions report the short names.
        - name: amenity_ids
          in: query
          required: false
          schema:
            type: string
          description: >-
            Comma-separated amenity IDs. A candidate must have all of them. See
            List Amenities.
      responses:
        '200':
          description: Ranked comp suggestions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompSuggestionsResponse'
              example:
                subject_property_id: 781245
                suggestions:
                  - property_id: 781266
                    rank: 1
                    score: 0.82
                    property_name: Marina Heights
                    address: 88 Lakeview Ave, Austin, TX 78703
                    distance_miles: 1.42
                    year_built: 2012
                    unit_count: 196
                    number_of_stories: 4
                    property_type: conventional
                    property_class: B
                    lease_up: false
                    in_comp_set: true
                  - property_id: 781390
                    rank: 2
                    score: 0.77
                    property_name: The Foundry
                    address: 1200 E 6th St, Austin, TX 78702
                    distance_miles: 2.08
                    year_built: 2024
                    unit_count: 310
                    number_of_stories: 6
                    property_type: conventional
                    property_class: A
                    lease_up: true
                    in_comp_set: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Forbidden - account_id is missing or the user lacks access to the
            requested account. A token that is not allowed to call the API, such
            as an MCP token, also gets 403 with an empty body.
        '404':
          description: >-
            Property not found, or comp_set_id is not an active comp set in the
            account that the user can open.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                property:
                  value:
                    error: Property not found
                comp_set:
                  value:
                    error: Comp set not found
        '422':
          description: The subject property can't be scored with this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                no_coordinates:
                  value:
                    error: Property must have coordinates
                property_type:
                  value:
                    error: property_type must include the subject property's type
        '429':
          $ref: '#/components/responses/RateLimitOrQuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    AccountId:
      anyOf:
        - type: integer
        - type: string
      description: ApartmentIQ account ID used to set the request account context.
    CompSuggestionsResponse:
      type: object
      properties:
        subject_property_id:
          type: integer
        suggestions:
          type: array
          items:
            $ref: '#/components/schemas/CompSuggestion'
      required:
        - subject_property_id
        - suggestions
    Error:
      type: object
      description: Error response payload.
      properties:
        error:
          type: string
          description: Short error message.
        message:
          type: string
          description: Additional error details, when available.
        quota_limit:
          type: integer
          description: Quota limit that applied to the request, when relevant.
        quota_usage:
          type: integer
          description: Quota already used, when relevant.
      required:
        - error
      additionalProperties: true
    CompSuggestion:
      type: object
      description: A ranked comp suggestion.
      properties:
        property_id:
          type: integer
        rank:
          type: integer
          minimum: 1
        score:
          type: number
          description: >-
            Comp score from 0 to 1. What a value means depends on the account's
            comp scoring version.
        property_name:
          type:
            - string
            - 'null'
        address:
          type:
            - string
            - 'null'
        distance_miles:
          type:
            - number
            - 'null'
          description: Distance from the subject property, rounded to 2 decimals.
        year_built:
          type:
            - integer
            - 'null'
        unit_count:
          type:
            - integer
            - 'null'
        number_of_stories:
          type:
            - integer
            - 'null'
        property_type:
          type: string
          enum:
            - conventional
            - student
            - senior
            - build_to_rent
            - affordable
          description: >-
            A property with more than one type reports the first match in this
            order: student, senior, build_to_rent, affordable.
        property_class:
          type:
            - string
            - 'null'
          enum:
            - A
            - B
            - C
            - D
            - null
        lease_up:
          type: boolean
          description: True when the property is leasing up.
        in_comp_set:
          type: boolean
          description: >-
            True when the property is a competitive comp in the comp set named
            by comp_set_id. Owned properties in that comp set show false.
      required:
        - property_id
        - rank
        - score
        - property_name
        - address
        - distance_miles
        - year_built
        - unit_count
        - number_of_stories
        - property_type
        - property_class
        - lease_up
        - in_comp_set
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Invalid or missing authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimitOrQuotaExceeded:
      description: >-
        A general API rate limit or account trial API quota was exceeded. For a
        trial quota response, quota_usage is the number of requests already
        counted and quota_limit is the account limit.
      headers:
        Retry-After:
          description: >-
            Seconds to wait before retrying when supplied by the active rate
            limiter.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Trial API quota limit exceeded
            quota_limit: 1000
            quota_usage: 1000
        text/plain:
          schema:
            type: string
          example: |
            You have exceeded the rate limit for this API.
    InternalServerError:
      description: An unexpected error occurred while processing the request.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.