API Documentation (GraphQL)

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

Interactive GraphiQL: Open the GraphiQL Explorer to run and validate the example GraphQL queries shown in this documentation.

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.

Learn how to use GraphQL with How to use 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"
}

Base properties (baseProperties)

The Insights Base Property query (baseProperties) returns U.S. assessor and public-record style property rows from the BaseProperties OData entity. Each row is keyed by CID together with county FIPS and parcel context. The GraphQL schema groups attributes into objects such as location, characteristics, structure, tax, latestTransfer, currentLoans, and estimatedValue, plus optional history expansions: historicalEstimate, taxHistory, salesAndTransferHistory, and mortgageHistory.

Connection result

Endpoint

POST /graphql

Root query (example)

query BasePropertyQuery(
  $filter: BasePropertyFilter!
  $limit: Int
  $offset: Int
  $orderBy: BasePropertySort
) {
  baseProperties(filter: $filter, limit: $limit, offset: $offset, orderBy: $orderBy) {
    totalCount
    nodes {
      cid
      countyFipsCode
      parcelNumber
      modificationTimestamp
      propertyType
      propertySubType
      location {
        address { unparsedAddress city stateOrProvince postalCode }
        census {
          administrative {
            countyOrParish {
              id
              name
              stateOrProvince
              country
              type
              geom
              latitude
              longitude
              version
            }
          }
        }
        gis { latitude longitude }
      }
      characteristics { lotSizeSquareFeet view poolFeatures }
      structure {
        bedroomsTotal
        bathroomsTotalInteger
        livingArea
        yearBuilt
      }
      latestTransfer { salesPrice recordingDate }
      estimatedValue { estimate confidenceScore }
      historicalEstimate(limit: 4) {
        estimateDate
        estimate
        rangeMin
        rangeMax
      }
      taxHistory {
        taxYear
        taxAnnualAmount
        taxAssessedValue
        marketValue
      }
      salesAndTransferHistory(limit: 5, orderBy: { modificationTimestamp: DESC }) {
        transactionId
        recordingDate
        salesPrice
        sellerFullName1
        buyerFullName1
        titleCompanyName
      }
      mortgageHistory(limit: 5, orderBy: { modificationTimestamp: DESC }) {
        loanId
        transactionId
        loanAmount
        interestRate
        loanType
        lenderNameBeneficiary
        recordingDate
      }
      resoProperties { listingKey }
    }
  }
}

Variables (example)

{
  "filter": {
    "countyFipsCode": { "eq": "06037" },
    "polygon": {
      "wkt": "POLYGON((-118.5 34.0, -118.3 34.0, -118.3 34.2, -118.5 34.2, -118.5 34.0))"
    },
    "structure": { "bedroomsTotal": { "ge": 3 }, "livingArea": { "ge": 1500 } },
    "estimatedValue": { "estimate": { "lt": 1000000 } },
    "dates": { "modificationTimeStamp": { "ge": "2026-01-01" } }
  },
  "limit": 10,
  "offset": 0,
  "orderBy": {
    "latestTransfer": { "recordingDate": "DESC" },
    "estimatedValue": { "estimate": "ASC" }
  }
}

How filtering works

Arguments use the input type BasePropertyFilter. The server forwards filters to Insights as an OData $filter string.

• Flat vs nested: You may pass a single “flat” object of conditions (e.g. countyFipsCode + structure). The resolver wraps it as { and: filter } when you do not supply top-level and or or, so all clauses are combined with AND.
• Explicit logic: To use OR or mixed logic, structure variables with top-level and or or keys whose values are objects of field filters (same pattern as other Insights-backed queries).
• Nested sections: Filters mirror the schema: e.g. location.address.city, structure.livingArea, latestTransfer.salesPrice, estimatedValue.estimate, dates.modificationTimeStamp.
• Polygon search: Use top-level polygon with wkt (a WKT POLYGON string of longitude/latitude pairs). The server maps this to OData geo.intersects(location, geography'POLYGON((...))'). The ring must be closed (first and last coordinate pair identical).
• Operators: StringFilter supports eq, contains, startswith; IntFilter and FloatFilter support eq, gt, ge, lt, le; DateTimeFilter supports eq, gt, ge, lt, le (ISO date strings).
• Enums: propertyType and propertySubType use GraphQL enums (e.g. Residential, SingleFamilyResidence) - pass them without wrapping in eq at the filter field.
• OData mapping: GraphQL cid maps to OData CID; dates.modificationTimeStamp maps to OData modificationTimestamp.

How sorting works

Use optional orderBy: BasePropertySort. Only certain leaf fields are mapped to OData $orderby:

Each sort direction is ASC or DESC (SortOrder enum). Multiple groups can appear in one orderBy object; the server builds a comma-separated OData order list.

How expansion works

In GraphQL, “expansion” means requesting nested fields in the query. There are no separate REST-style expand parameters.

• Nested objects: Ask for location { address census gis }, tax { … }, occupantOwner { … }, etc. Null objects appear when the source has no data.
• location.gis.parcel: Resolved via DataLoader / ParcelBoundary API by CID (extra round-trip when selected).
• History fields: Request historicalEstimate, taxHistory, salesAndTransferHistory, or mortgageHistory under each BaseProperty node. Each loads a related Insights history entity by CID (batched). Omit them to avoid the extra work. If Insights denies a history entity (HTTP 403), that field resolves to null and GraphQL may include an entry in errors while the rest of baseProperties still returns.
• resoProperties: When listed under BaseProperty, the resolver loads linked MLS/RESO listings for the same CID (batched per request). Omit this field to avoid that work.

Pagination

Operators (filter leaf inputs)

BaseProperty - root fields (schema)

Nested highlights: location.address (full addressing components); location.census (administrative, legislative, statistical GeoIDs and boundary details); location.gis (lat/long, precision, parcel boundary); latestTransfer.buyers/sellers arrays; currentLoans.loans array of BaseLoan.

Historical fields (schema detail)

History fields are requested on each BaseProperty node. They are not part of the root BasePropertyFilter; filtering and sorting for history apply only to that field’s arguments. If the caller’s Insights credentials lack access to a history entity, that field returns null (with a GraphQL error) and the rest of the base property payload is unchanged.

historicalEstimate → [BaseHistoricalEstimate!]

Backed by OData AvmHistoryAggregate. Returns monthly AVM point estimates for the property.

taxHistory → [BaseTaxHistory!]

Backed by OData AssessorHistoryAggregate. Returns annual tax and assessment history.

See GraphQL introspection for the full BaseTaxHistory leaf list (exemptions, certification date, value-per-sqft fields, and related flags).

salesAndTransferHistory → [BaseSalesAndTransferHistory!]

Backed by OData SalesAndTransferHistory. Returns recorded sales and ownership transfers for the property.

mortgageHistory → [BaseMortgageHistory!]

Backed by OData MortgageHistoryAggregate. Returns historical mortgage and lien records for the property.

See GraphQL introspection for the complete BaseMortgageHistory and BaseSalesAndTransferHistory field lists.

Example history selection

nodes {
  cid
  estimatedValue { estimate confidenceScore }
  historicalEstimate(limit: 12, orderBy: { estimateDate: DESC }) {
    estimateDate
    estimate
    rangeMin
    rangeMax
  }
  taxHistory(filter: { taxYear: { ge: 2018 } }, orderBy: { taxYear: DESC }) {
    taxYear
    taxAnnualAmount
    taxAssessedValue
    marketValue
  }
  salesAndTransferHistory(limit: 10, orderBy: { modificationTimestamp: DESC }) {
    transactionId
    recordingDate
    salesPrice
    buyerFullName1
    sellerFullName1
  }
  mortgageHistory(limit: 10, orderBy: { modificationTimestamp: DESC }) {
    loanId
    loanAmount
    interestRate
    lenderNameBeneficiary
    recordingDate
  }
}

CensusGeo fields (used under location.census.*)

Example response (abbreviated)

{
  "data": {
    "baseProperties": {
      "totalCount": 1,
      "nodes": [{
        "cid": "06037123456",
        "countyFipsCode": "06037",
        "parcelNumber": "1234-567-890",
        "modificationTimestamp": "2026-01-10",
        "propertyType": "Residential",
        "structure": { "bedroomsTotal": 4, "livingArea": 2500 },
        "estimatedValue": { "estimate": 1012000, "confidenceScore": 95 }
      }]
    }
  }
}

RESO listings (resoProperties)

The resoProperties query returns MLS listing rows modeled as RESO-style groups (listing, location, structure, tax, financial, etc.). Filters are translated to OData against the RESO listings endpoint; results expose rich nested objects on each RESOProperty.

Connection result

Endpoint

POST /graphql

Root query (example)

query ResoListings(
  $filter: RESOPropertyFilter!
  $limit: Int
  $offset: Int
  $orderBy: RESOPropertySort
) {
  resoProperties(filter: $filter, limit: $limit, offset: $offset, orderBy: $orderBy) {
    totalCount
    nodes {
      cid
      listingKey
      propertyType
      propertySubType
      listing {
        standardStatus
        listPrice
        closePrice
      }
      location {
        address {
          unparsedAddress
          city
          stateOrProvince
          postalCode
        }
      }
      baseProperty {
        countyFipsCode
        parcelNumber
      }
    }
  }
}

Variables (example)

{
  "filter": {
    "listing": {
      "standardStatus": { "eq": "Active" }
    },
    "location": {
      "address": {
        "stateOrProvince": { "eq": "CA" }
      }
    }
  },
  "limit": 10,
  "offset": 0,
  "orderBy": {
    "price": { "listPrice": "DESC" },
    "dates": { "modificationTimestamp": "DESC" }
  }
}

How filtering works

• Input type: RESOPropertyFilter with top-level cid, listingKey, propertyType, location, listing.
• Listing subtree: listing.originatingSystemName, listing.standardStatus, listing.price (close/list/previous prices), listing.dates (status/modification/close/on-market/off-market timestamps, days on market), listing.agentOffice (buyer/list/co agents & offices), listing.structure, listing.equipment, listing.leaseAmount, listing.rawMlsPropertySubType.
• Location subtree: location.address.* for street, city, state, postal, county, etc. - each uses RESO StringFilter with eq, ne, contains, startsWith as defined on that schema.
• Operators: Strings use comparison filters as noted above; numeric fields use FloatFilter and IntFilter; dates use DateTimeFilter with eq, gt, ge, lt, le.
• Combining: Same as base properties: omit top-level and or or for an implicit AND bundle, or supply explicit logical objects when your client passes structured filters.
• Backend: Built server-side into OData for the Property/listings service (not the same entity set as BaseProperties).

How sorting works

orderBy: RESOPropertySort supports nested groups:

Use ASC or DESC per field. Only mapped fields are sent to the listings OData layer.

How expansion works

• Select any subset of RESOProperty groups: business, characteristics, equipment, farming, financial, hoa, listing, location, occupantOwner, structure, tax, unitTypes, utilities, identifiers (universalPropertyId, etc.).
• baseProperty: Joins to Insights Base Property by CID - include only when you need assessor/public-record fields to avoid an extra Insights fetch per listing.

RESOProperty - root groups (schema)

See the GraphQL schema / introspection for the full list of leaf fields inside each group.

Pagination

Schools (schools)

The schools query reads the Insights Schools OData entity. Each School node is one school record; filters are flat OData column names (no nested filter objects like Base Property).

Connection result

Endpoint

POST /graphql

Root query (example)

query SchoolsQuery(
  $filter: SchoolFilter!
  $limit: Int
  $offset: Int
  $orderBy: SchoolSort
) {
  schools(filter: $filter, limit: $limit, offset: $offset, orderBy: $orderBy) {
    totalCount
    nodes {
      id
      name
      status
      modificationTimestamp
      location {
        address { city stateOrProvince postalCode }
        gis { countyFipsCode latitude longitude }
      }
      classification { level gradeRangeMin gradeRangeMax charterYN }
      enrollment { studentsTotal studentTeacherRatio }
      district { id name status }
      testScores { testYear subjectName percentMetStandard }
      schoolRatings { schoolRating schoolRank schoolRankYear }
    }
  }
}

Variables (example)

{
  "filter": {
    "stateOrProvince": { "eq": "CA" },
    "city": { "contains": "Los Angeles" }
  },
  "limit": 25,
  "offset": 0,
  "orderBy": { "name": "ASC" }
}

How filtering works

• Flat filters: Every key on SchoolFilter maps to a single OData property (e.g. city, studentsTotal, latitude). There is no location.address.city path in the filter - use city directly.
• Operators: Same primitives as elsewhere: StringFilter (eq, contains, startswith), plus IntFilter, FloatFilter, and BooleanFilter for fields such as charterYN.
• Combining: Resolver wraps plain objects in { and: ... } when you omit explicit and or or.
• Strings in OData: Insights double-quotes certain school string literals for OData compatibility - handled inside the API client.

How sorting works

SchoolSort exposes top-level fields only. Mapped OData columns include:

Directions: ASC or DESC. Only one field per group is typical; multiple entries depend on server mapping (comma-separated OData).

How expansion works

• district: Resolver loads SchoolDistrict via districtId + DataLoader (batched).
• testScores: Loads TestScores rows where schoolId equals this school’s id.
• schoolRatings: Loads accountability/rating rows for the school id.
• Omit these fields in the GraphQL selection set when you do not need them to reduce Insights calls.

School - fields by level (schema)

Pagination

limit maps to OData $top, and offset maps to $skip.

School districts (schoolDistricts)

The schoolDistricts query reads the Insights SchoolDistricts OData entity. Filters use flat district columns; expansions load related schools and test rows by foreign key.

Connection result

Endpoint

POST /graphql

Root query (example)

query SchoolDistrictsQuery(
  $filter: SchoolDistrictFilter!
  $limit: Int
  $offset: Int
  $orderBy: SchoolDistrictSort
) {
  schoolDistricts(
    filter: $filter
    limit: $limit
    offset: $offset
    orderBy: $orderBy
  ) {
    totalCount
    nodes {
      id
      name
      status
      modificationTimestamp
      location {
        address { city stateOrProvince postalCode }
        gis { countyFipsCode countyOrParish }
      }
      composition {
        gradeRangeMin
        gradeRangeMax
        numberElementarySchools
        numberMiddleSchools
        numberHighSchools
      }
      ratings { districtRating districtRank districtRankYear }
      graduation { graduationRate graduationRateYear }
      schools { id name level status }
      testScores { testYear subjectName percentMetStandard }
    }
  }
}

Variables (example)

{
  "filter": {
    "stateOrProvince": { "eq": "TX" },
    "name": { "contains": "Independent" }
  },
  "limit": 10,
  "offset": 0,
  "orderBy": { "name": "ASC" }
}

How filtering works

• Flat filters: Keys on SchoolDistrictFilter map 1:1 to OData properties (e.g. name, city, districtRating, numberElementarySchools).
• Operators: Identical vocabulary to schools (eq, contains, startswith, plus numeric comparisons).
• Combining: Implicit and wrapping when and or or is omitted at the top level.

How sorting works

How expansion works

• schools: Batch-fetches all School rows whose districtId equals this district’s id (large result sets possible - use pagination on the parent query and narrow filters).
• testScores: TestScores joined with schoolId equal to the district id (same identifier space as documented on TestScore).

SchoolDistrict - fields by level (schema)

Pagination

Same as schools: limit maps to OData $top, and offset maps to $skip.