The search resources allows you to search for classified ads much similar to www.finn.no.
Links to the search resources are listed in the searhes workspace in the Service Document. Here they are identified by rel="search" and category with scheme uri: scheme="urn:finn:market".
Searches are defined in the Atom format, extended by the OpenSearch extension. Please refer to these standards for documentation. Alongside these well-established standards, we've seen the necessity of establishing our own extensions, defined in the f and finn namespaces. A search is defined as an Atom feed. This feed has entries. These are the search results. The entries have finn:adata elements. These represent the data of each ad found in the search. The contents should be self-explanatory, but are also supported by the model, defining each finn:adata element. The model href is found in the model -attribute.
https://cache.api.finn.no/iad/search/
GET HEAD
There are limitations to the volume of search results returned. Clients should be well within these limits. Exceeding the limits will return 200 OK, but no additional results.
Max number of rows: 1000 (rows=1000) Max number of pages: 50 (page=50)
The OpenSearch 1.1 spec with the OpenSearch parameters extension defines search parameters. This is used for all cross-market/FINN-vertical searches. Examples are keyword, geo, organization id, age, paging and sorting parameters.
In addition to these cross-market parameters, the API also provides more complex filtering. These filters are defined as extensions to the OpenSearch 1.1 description standard, and must be viewed as market specific although naming can be consistent across markets. Examples of these filters are price_from, color etc. These filters are also defined in the OpenSearch description document, navigatable from the search itself and the service document - or API entry point - and can be identified by the rel="search" with type="application/opensearchdescription+xml". The description lists available filters and describes whether they are range filters or single value filters. E.g. price is a range filter: <f:filter range="true" name="price"/ > expands to the filters price_from and price_to. This is valid for all range filters. Single value filters are not expanded, and should be used directly as read from the OpenSearch description document.
The value definition of filters are found in the search feed itself, due to being strictly dependent on the search being executed. An open search, without filters or parametes, will provide all valid filters for a base level search. Eg. an empty search made to the resource defined by a link with rel="search" and scheme="urn:finn:market" with the term="car-norway" will provide full taxonomy filters for make, model, color, price, year etc. These values, found in the search itself, should be used to populate UI components with valid filters for the next search. An example of a search query string for ATV searches - disregarding the url itself - is ?price_from=25000 & price_to=300000 & year_from=1994 & make=7917 & location=20017 wich will search for an ATV with a price in the range of 25000-300000, made after and including 1994, with the make Arctic Cat (filter values can differ from the actual name) in the region of Nord-Trøndelag. This is a typical search withouth any taxonomy, or levelled, filters. An example of a taxonomy filter is the filter location on realestate searches: ?location=0.20003 & location=1.20010.20166 . This query string will search for ads in Akershus (0.20003) and Arendal (1.20010.20166). These locations can be found at different levels in our location hierarchy, and a full taxonomy value must be provided in order for us to provide the correct boolean logic between these filter values. Do not make any assumptions on values being taxonomies or not, strictly read the f:filter values from the f:Query tags. A filter can have the same name across markets, but may differ in taxonomy levelling and may not be a taxonomy at all. Searches across markets should be read separatly.
An excerpt from a search for BAP ads (Torget) might contain the following filters:
<f:filter name="location" title="Område" range="false">
<f:Query role="subset" totalResults="7082" f:filter="0.20015" title="Møre og Romsdal">
<f:filter name="location" title="Område" range="false">
<f:Query role="subset" totalResults="565" f:filter="1.20015.20281" title="Kristiansund" />
<f:Query role="subset" totalResults="49" f:filter="1.20015.20301" title="Nesset" />
</f:filter>
</f:Query>
</f:filter>
<f:filter name="category" title="Kategori" range="false">
<f:Query role="subset" totalResults="33936" f:filter="0.90" title="Bil-, MC- og båtutstyr">
<f:filter name="sub_category" title="Underkategori" range="false">
<f:Query role="subset" totalResults="762" f:filter="1.90.3974" title="Annet" />
<f:Query role="subset" totalResults="22504" f:filter="1.90.82" title="Bil">
</f:filter>
</f:Query>
</f:filter>Samples of search outputs:
Current query parameters are shown in the rel="self" link.