Basic Requests

Following OData protocol, the following examples show how combining options and filters can retrieve a desired subset of data results.

GET /odata/Assessor?$select=...&$filter=...&$top=...&$orderby=...&$skip=...

API response structure

{
  "@odata.context": "...",
  "@odata.total_count": 100,
  "@odata.count": 0,
  "@odata.nextLink": "...",
  "value": []
}

Select

By default, the entire set of fields are returned, however, we can whitelist specific fields in the response using $select. Whitelist fields are specified in a comma separated list.

Example request:

GET /odata/assessor?$select=CountyFipsCode,TotalAssessedValue

Example response:

{
"@odata.context": "https://insights.cdatalabs.com/$metadata#Assessor",
"@odata.total_count": 100,
"@odata.count": 10,
"@odata.nextlink": "https://insights.cdatalabs.com/odata/assessor/12wqewqeqqxcz4ewogICJGcm9tIjogMTAwLAogICJTaXplIjogMTAwLAogICJUaW1lU3RhbXAiOiA2Mzg1MzA5MTkzMDYzNzA3NjIKfQ==/?$select=CountyFipsCode,TotalAssessedValue"
"value": [
{
"CountyFipsCode": "35043",
"TotalAssessedValue": 86516
},
{
"CountyFipsCode": "35001",
"TotalAssessedValue": 103504
}
...
]
}

Top

By default, the first 100 results are returned in any API request, however we can alter the number of results by using the $top option followed by a non-negative integer value.

Example request:

GET /odata/Assessor?$top=1

Recommendation: It is recommended to not exceed $top=100. Exceeding this limit will cause slowness of response payloads

Skip

Often in combination with $top**, the **$skip option allows for client side paging, also using a non-negative integer we can cycling through the entire result set.

Example request:

GET /odata/Assessor?$top=5&skip=2

Recommendation: It is recommended to use this approach for shallow (small dataset) paging. Using this approach for more than 1 million records will cause slowness in response.

SkipToken

When working with large datasets, our OData API supports pagination to efficiently manage the data retrieval process. This is achieved using the @odata.nextLink property, which provides a URL to the next page of results.

Initial request:

Begin by making a GET request to the desired endpoint. The response will include the first set of results along with ‘@odata.nextLink’ property if more data is available.

Example initial request:

GET /odata/Assessor?$expand=Deeds&$filter=StateOrProvince eq 'CA'

Recommendation: It is recommended to use this approach for paging large datasets.

Checking for ‘@odata.nextLink’

After receiving the initial response, inspect the JSON payload for the @odata.nextLink property. This property contains the URL for the next page of results. If this property is present, it indicates that there are additional pages of data to retrieve.

Sample JSON response:

{
"@odata.context": "https://insights.cdatalabs.com/$metadata#Assessor",
"@odata.total_count": 100,
"@odata.count": 100,
"@odata.nextlink": "https://insights.cdatalabs.com/odata/Assessor/skiptoken/ewogICJGcm9tIjogMTAwLAogICJTaXplIjogMTAwLAogICJUaW1lU3RhbXAiOiA2Mzg1MzE4ODQ2NDM4NzQ4NTYKfQ==/?$expand=Deeds&$filter=StateOrProvince+eq+'CA'",
"value": [...]
}

Fetching Subsequent Pages

To retrieve the next set of results, make another HTTP GET request to the URL specified in the ‘@odata.nextLink’ property. Repeat this process, checking each response for a new @odata.nextLink, until this property is no longer present.

Example of fetching next page:

GET https://insights.cdatalabs.com/odata/Assessor/skiptoken/ewogICJGcm9tIjogMTAwLAogICJTaXplIjogMTAwLAogICJUaW1lU3RhbXAiOiA2Mzg1MzE4ODQ2NDM4NzQ4NTYKfQ==/?$expand=Deeds&$filter=StateOrProvince+eq+'CA'

Looping Until All Data is Retrieved

Continue the pagination process in a loop until no @odata.nextLink is found. This ensures that all pages of data are retrieved sequentially.

Best Practices

1. Error Handling: Implement robust error handling to manage network issues, API rate limits, and other potential errors.
2. Data Processing: Consider processing each page of data as it is fetched to avoid excessive memory usage.
3. Respect Rate Limits: Be mindful of the API’s rate limits to prevent throttling or blocking.

Filter

Most common option is $filter, typically at least one filter is used when retrieving data, often used are comparison operators to filter results by an MLS (Data Source) via the OriginatingSystemName field.

The following is a list of supported operators and expressions. In future additional OData expressions  could be added to the API.

Comparison Operators

Note: single quotation is required for string values

Boolean Operators

Note: boolean operator is expressed in lower cased

Often used to chain multiple comparison expressions, the boolean operators and and or can precise subset of data

Expand

In OData, the $expand** allows for retrieval of supplementary entity data where there is an association to the primary entity. Typically **$expand would be used where Property is the primary EntityType. Expand can retrieve multiple sub-entities using a comma separated list.

Example requests:

GET /odata/Assessor?$expand=Deeds
GET /odata/Assessor?$expand=Deeds,Mortgage

Recommendation: It is recommended to not exceed $top=100 with$expand as $expand increases the payload size and query time, potentially resulting in a degradation of service.

Ordering

To sort results, the $orderby option can be used, providing the desired sort field and direction, if direction is not provided by default it is assumed the sort order is ascending. Multiple order by expressions can be provided by a comma separated list.

Example requests:

GET /odata/Assessor?$orderby=CID
GET /odata/Assessor?$orderby=CID desc
GET /odata/Assessor?$orderby=CID desc, AssessedLandValue asc