Request Parameters
Bright MLS data services allow you to modify the request to specify certain fields, search data to narrow down the selection, and then limit and order the results.
Headers
The following headers are required:
| Field | Value |
|---|---|
| User-Agent | Bright WebAPI/1.0 |
| Authorization | Bearer [token] |
| Cache-Control | no-cache |
| Host | [http client] |
Note that we accept custom User-Agents but we require to add them prior to connection. Please see the FAQ.
Multiple parameters can be queried, but each parameter can only be called once. You cannot specify more than one set of $filter options for example.
Attribute Selection
The $select parameter allows you to specify fields to returned in the data set. This should be used often to narrow down to required fields, especially with resources containing large amounts of fields to improve response time.
The presence of a field in the metadata and in the $select parameters does not automatically provide access to that field's data. Access to a particular field is based on your credentials and roles allocated to you.
| Parameter | Description |
|---|---|
| $select | A comma separated list specifying the attributes to be returned in the response payload. |
Pagination
Pagination allows you to retrieve data is specified sets and provides information on how much data is available to iterate. This parameter is useful for replication as well as there are response limits.
The most efficient method of pagination is through the oData.nextLink method, which allows the client to specify a max page size for nextLink, and a link is then provided at the end of the results to query the next set of data. This is the fastest and safest method of pagination as the paged results are not affected by changes in data during pagination. When the last page of data is sent, the nextLink option will be absent from the end of the results, and $count query parameter can be used in conjunction with nextLink header option.
To implement oData.nextLink, add the following header to any resource query:
| Header Key | Header Value |
|---|---|
| Prefer | odata.maxpagesize=n |
The response will automatically then include an odata.nextLink key with the URL, including parameters, to obtain the next page of data. Example:
Alternatively, you can use $top and $skip to paginate, though performance is significantly worse on queries with a large number of results.
| Parameter | Description |
|---|---|
| $top | Integer > 0 indicating how many results to return at once. |
| $skip | Indicates the number of records to skip over. |
| $count | Boolean true or false. Indicates if the number of records in the total result set should be returned. Default is false. |
Sorting
Sorting is usually available on resources that allow filtering.
| Parameter | Description |
|---|---|
| $orderby | Indicates the order in which to return records in the result set. Each service has its own default order. |
| Any field available in filters can be present in the $orderby parameter, with some exceptions (e.g. longer text fields such as PublicRemarks for properties). |
Filtering
Request parameters below are common to data retrieval services supporting searching.
| Parameter | Description |
|---|---|
| $filter | OData filter syntax is used for filtering. |
Filtering Operators
These parameters allow you to specify values for filtering and join multiple filtering options.
| Option | Description |
|---|---|
| eq | Equal to |
| ne | Not Equal to |
| gt | Greater than |
| ge | Greater than or equal to |
| lt | Less than |
| le | Less than or equal to |
| has | The operator returns true if the right hand operand is an enumeration whos flags are set on the left operand |
| in | Allows providing a comma-separated array of values inside parenthesis to compare against |
| and | Combine filter options requiring all to be true |
| or | Combine filter options requiring one to be true |
Count
To return a total count of records for the filtered query, you can add the $count parameter.
Format
This parameter can be used to force the server response into either JSON or XML format.
| Parameter | Option | Description |
|---|---|---|
| $format | json | Server response in JSON format. |
| $format | xml | Server response in XML format. |