Faceting & Auto-Complete

To auto-complete the user input or show various configuration available on a VIN or car you can use faceting feature in Marketcheck API. Using faceting you can fetch unique values / terms / tokens for a field. By extending this faceting feature we’ve provided another endpoint that lets developers autocomplete the end users input strings. To understand more about this useful feature of Marketcheck API and how to use it, please read on…

What is Faceting in Marketcheck API?

Faceting in Marketcheck search and auto-complete APIs allows developers to fetch unique values / terms / tokens for a field. So if you want all unique values of all car make then you need to fetch facets on make field. The API response will contain all values for make field (like Ford, Chevrolet, Nissan etc).

As Marketcheck API contains live inventory data for all of US and Canada market, we are also able to provide counts / inventory levels of each configuration via facets. For example — When you request facets on make, Marketcheck API along with unique terms for that field (in this case — make) also returns the active counts of cars for sale of that make. So you would also be able to see the counts of all Fords, Chevrolets and Nissans that are up for sale.

How to use facets feature?

Facets are available in mainly two modes —

1. Plain facets with counts. Like in search APIs
2. Auto-complete facets with just terms. Like in Taxonomy autocomplete APIs

Facets in Search APIs

In search APIs you can request facets on various fields, here you would get all unique terms plus the counts of those facet terms. You can find list of all the fields on which facets are allowed on API docs — https://apidocs.marketcheck.com/#8f2b5cec-52fa-498c-a55c-36b22820a274

To request facets on a field you need to include facets parameter in your URL, with it’s value being the field name for which you want facets.

Example — To request facet on field - make

https://marketcheck-prod.apigee.net/v2/search/car/active?api_key={{api_key}}&rows=0&facets=make

Note : Replace {{api_key}} in above request with your API key. To obtain a new API key, sign up at Marketcheck developer portal — https://www.marketcheck.com/

Pagination & facets on multiple fields

By default API returns top 20 terms (sorted on count) for any facet field. You can request more terms in a single API call and also paginate the result if there are more unique terms. To request more terms in a single API call, you need to provide offset and limit / terms count along with field name, separated by pipe, Like —

facets={{field_name}}|{{offset}}|{{limit}}

Here field name can be any field on which facets are allowed and offset and limit are numeric numbers. So if in first call you requested 100 facet terms from start with offset and limit being 0 and 100, in next API call to paginate the result you need to provide offset as 100 and limit as 100 and in next offset as 200 and limit as 100 and so on. More on this here.

The maximum value of limit is 1000. You can not get more than 1000 unique terms for a field in single API call. If any field has more than 1000 terms then you need to use offset to paginate the results in increments of 1000.

For example, To fetch all terms of make field (beyond top 20), provide value of facets parameter like —

facets=make|0|100

You can also request facets on multiple fields in one API call by mentioning all field names in facets parameters value, separated by comma.

So suppose to get all year values as well (along with make) you can make an API request like —

https://marketcheck-prod.apigee.net/v2/search/car/active?api_key={{api_key}}&rows=0&facets=make|0|100,year|0|100

Filtering the results first

One of the most important use case of facets is you can request facets on a field after filtering the result set first. So if user has selected some make as his preferred one and now you want to show him model’s of that make, you can do so with Marketcheck search API. You can use make parameter of the search API to filter the results for one particular make and then use facets parameter to fetch it’s models, like —

https://marketcheck-prod.apigee.net/v2/search/car/active?api_key={{api_key}}&rows=50&make=ford&facets=model|0|1000

Note : Here assuming user has requested Ford cars, and now you make API call to fetch all ford cars and use rows=50 to get ford listings, you can request facets on model in same API call to show in your drill downs

There are numerous parameters available in search API that you can use to filter the result set. You can find out all the available parameters at Marketcheck API documentation.

For example, if you want to filter the results to your (users) local market only (Suppose Houston Texas) then you can do so like —

https://marketcheck-prod.apigee.net/v2/search/car/active?api_key={{api_key}}&rows=50&make=ford&facets=model|0|1000&city=Houston

Or by using a geo-location parameters like zip or lat-long and radius —

https://marketcheck-prod.apigee.net/v2/search/car/active?api_key={{api_key}}&rows=50&make=ford&facets=model|0|1000&zip=77034&radius=5

Sorting

Facet results are always sorted on count by default. As mentioned earlier, in Search APIs we also have live inventory counts of each configuration and results are sorted on these inventory counts. So any make that has most cars for sale in the market will appear at top of the facets results. Similar is the case for all other fields as well, like if you request facets on models of ford then in result you would get model terms sorted on their inventory count.

There is one more sort available in facets and that is by index (alphabetically). With index sort you can sort results alphabetically (Ascending only). To change facet sort you need to use facet_sort parameter with its value being either count or index

https://marketcheck-prod.apigee.net/v2/search/car/active?api_key={{api_key}}&rows=0&facets=make&facet_sort=index

Autocomplete APIs

By extending this facets feature internally we’ve provided one more API endpoint — auto-complete to provide car taxonomy auto completion feature. Here in Autocomplete API you only get terms of that field that match the user input so far.

As user might input make first and the type first few letters of model name, in Autocomplete API we’ve provided combination fields to handle such inputs as well. You can find out list of all fields on which autocomplete is allowed here in documentation. You’ll also see that there are combination fields like ymm (year-make-model) and mm(make-model) on which autocomplete is allowed.

You need to provide a field name (on which autocomplete is needed) and input string (the text user has entered so far) in request url. For example —

https://marketcheck-prod.apigee.net/v2/search/car/auto-complete?api_key={{api_key}}&field=mm&input=ford f-

Please refer to Marketcheck API’s documentation for more details on Autocomplete APIs

Facets in Taxonomy/Decoder APIs

The facets in search APIs are mainly about the inventory levels of each car configuration. They are perfect for any car search portal that shows cars for sale in US and CA. But if you want terms / values of a field regardless if any car with that specification is up for sale or not then these Taxonomy Facets API are perfect for you.

Here the facets you get are sourced from our entire decoder database and not the inventory data that we crawl, as such this data is bit raw but provides you every possible value of a field. As this data does not have inventory level counts attached to it, the results are always sorted alphabetically (ASC)

For example to fetch all make terms —

https://marketcheck-prod.apigee.net/v2/specs/car/terms?api_key={{api_key}}&field=make

Please note the change in endpoint as well

You can also request facets on multiple fields in one go and paginate the results if there are too many terms for a field, just like with facets in search API. You can read more details about this on documentation

Conclusion

Facets are really useful feature of search API and you can use them in variety of manners. If you foresee any new scenario where facets can be used or want any assist with using them in your application, please feel free to reach out to us at — api@marketcheck.com