API Documentation (GraphQL)

The Insights GraphQL API combines the RESO Listings with the Insights OData APIs to provide a combined result set.

This API uses GraphQL, which is a query language with the ability to define precisely the data you want to fetch

The GraphQL query is resolving our Listings API (MLS data) and our Insights API (Public Records) API in a single call.

You can read more about Listings API here

You can read more about Insights API here

Learn how to use GraphQL with How to GraphQL

Authentication

Access to the API utilizes OAuth2.

Client Credentials (ID and secret) are provided for each user of the API, allowing for retrieval of bearer access token with preset expiry (default 3600 seconds).

We must encode the combination of Client ID and Client Secret Key separated by ":" in Base 64 format like this:

Base64Encode(5pq9999coididi613e222o1nnpp: fhkoq33a69d8191j1tercv35037clb9e5a7d215e64e4e) = 85e1b0e7539a4a96b00ee02b335aa6418c580917a6b4667f6f7a6fe2149536041569924dfbe4a7df33f==

Can use online service Base64Encode for the encoding.

The end point for the token must include two parameters with optional scope parameter:

1. "grant_type" = "client_credentials"
2. "client_id" = "5pq9999coididi613e222o1nnpp"
3. To authenticate successfully, if providing scope parameter, ensure the scope is set to either:
   "scope" = "" (empty string) or "scope" = "https://api.constellation1apis.com/Api.Read" depending on your integration requirements.

Example request to retrieve access token:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic 85e1b0e7539a4a96b00ee02b335aa6418c580917a6b4667f6f7a6fe2149536041569924dfbe4a7df33f==" \
-H "Host: authenticate.constellation1apis.com" \
"https://authenticate.constellation1apis.com/oauth2/token?grant_type=client_credentials&client_id=5pq9999coididi613e222o1nnpp"

Authentication response:

{
    "access_token": "**********************************",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Core Property GraphQL API

The Core Property API provides unified access to U.S. public records through a single standardized GraphQL endpoint. Each property record is uniquely identified using a combination of CID, Parcel Number, and County FIPS Code. Through this API, you can retrieve complete, normalized property data including: Location, Characteristics, Structure, Ownership, Tax, Transfer, Mortgage, and Estimated Value (AVM) - all in one query.

The GraphQL endpoint standardizes data from multiple sources and counties into RESO-aligned field names and types. By using filters, pagination, and sorting, you can query any subset of property data efficiently and consistently.

Endpoint

POST /graphql

Root Query

query BasePropertyQuery($filter: BasePropertyFilter!, $limit: Int, $offset: Int, $orderBy: BasePropertySort) {
  baseProperties(filter: $filter, limit: $limit, offset: $offset, orderBy: $orderBy) {
    totalCount
    nodes {
      cid
      countyFipsCode
      parcelNumber
      propertyType
      propertySubType

      location {
        address {
          unparsedAddress
          city
          stateOrProvince
          postalCode
        }
        gis {
          latitude
          longitude
        }
      }

      characteristics {
        lotSizeSquareFeet
        view
        poolFeatures
      }

      structure {
        bedroomsTotal
        bathroomsTotalInteger
        livingArea
        yearBuilt
        architecturalStyle
      }

      latestTransfer {
        salesPrice
        recordingDate
        buyers { fullName }
        sellers { fullName }
      }

      estimatedValue {
        estimate
        confidenceScore
      }
    }
  }
}
  

Variables

{
  "filter": {
      "countyFipsCode": { "eq": "06037" },
      "structure": {
        "bedroomsTotal": { "ge": 3 },
        "livingArea": { "ge": 1500 }
      },
      "estimatedValue": { "estimate": { "lt": 1000000 } }
  },
  "limit": 10,
  "offset": 0,
  "orderBy": {
    "latestTransfer": { "recordingDate": "DESC" },
    "estimatedValue": { "estimate": "ASC" }
  }
}
  

Filter Syntax

The BasePropertyFilter input accepts nested filters for different property sections. You must wrap field-level filters under either a logical and or or block.

{
  "filter": {
      "countyFipsCode": { "eq": "06037" },
      "structure": { "yearBuilt": { "ge": 2010 } },
      "estimatedValue": { "estimate": { "lt": 1500000 } }
  }
}
  

Sorting

Use orderBy to sort results on one or more fields. You can specify nested sort groups, for example:

"orderBy": {
  "structure": { "livingArea": "DESC" },
  "latestTransfer": { "salesPrice": "DESC" }
}
  

Pagination

Example Response

{
  "data": {
    "baseProperties": {
      "totalCount": 1,
      "nodes": [
        {
          "cid": "06037123456",
          "countyFipsCode": "06037",
          "parcelNumber": "1234-567-890",
          "propertyType": "Residential",
          "propertySubType": "Single Family",
          "location": {
            "address": {
              "unparsedAddress": "123 Main St, Los Angeles, CA 90001",
              "city": "Los Angeles",
              "stateOrProvince": "CA",
              "postalCode": "90001"
            },
            "gis": {
              "latitude": 34.0522,
              "longitude": -118.2437
            }
          },
          "characteristics": {
            "lotSizeSquareFeet": 7500,
            "view": ["City", "Hills"],
            "poolFeatures": ["Private"]
          },
          "structure": {
            "bedroomsTotal": 4,
            "bathroomsTotalInteger": 3,
            "livingArea": 2500,
            "yearBuilt": 2018,
            "architecturalStyle": ["Modern"]
          },
          "latestTransfer": {
            "salesPrice": 985000,
            "recordingDate": "2024-11-05",
            "buyers": [{ "fullName": "John Doe" }],
            "sellers": [{ "fullName": "Smith Family Trust" }]
          },
          "estimatedValue": {
            "estimate": 1012000,
            "confidenceScore": 95
          }
        }
      ]
    }
  }
}
  

Key Highlights

• Nested filtering: Supports deep filters like structure.yearBuilt or estimatedValue.estimate.
• Normalized arrays: Fields like view, roof, parkingFeatures are always arrays.
• Consistent schema: All properties across counties follow the same RESO-compliant structure.
• Full-text support: Use contains or startswith in text filters for flexible searching.
• Built-in sorting: Multi-level sort on sales price, year built, or AVM estimate.

Sample Use Cases

• Get the 10 most recent home sales in a county:

"filter": { "countyFipsCode": { "eq": "06037" } },
"orderBy": { "latestTransfer": { "recordingDate": "DESC" } },
"limit": 10
    

• Find homes with large lots and pools:

"filter": {
    "characteristics": { "lotSizeSquareFeet": { "ge": 10000 } },
    "structure": { "poolFeatures": { "contains": "Private" } }
}