If you got your API-key and are ready to do some coding this tutorial will help you get started.

1. Make sure your API-key is working

Try a simple curl-command and see if you get a "200 - OK" :

curl -I -H 'x-FINN-apikey: <API-key>' https://cache.api.finn.no/iad/

If it all went ok, the first line in the response should state:

HTTP/1.1 200 OK

"403 Forbidden" indicates that your API-key is not working. If you just got the key, please try again after an hour. It might take some time for the key to be initiated.

Alternative to Curl

As an alternative to Curl you can use severel rest plugins to your browser. Here is how check your API-key with DHC REST Client in Chrome:

  • Install the DHC REST Client plugin for Chrome.
  • Start the plugin. There is a button on the page from where you installed the plugin that you can use to open the plugin in Chrome. See below screenshot, click to enlarge.
  • In the url field enter: https://cache.api.finn.no/iad/

    Click the + sign to add a header. As header name use: x-FINN-apikey

    As value for the header, enter the api-key you have been assigned. See below screenshot for help, click on the image to enlarge.

2. Get familiar with the Service Document

The Service Document is the "frontpage" of the APIs. It contains links to other endpoints or resources. Not all resources may be available to you, but chances are "/iad/search/*" and "/iad/ad/*" are.

The Service Document contains several Workspaces describing different types of resources. It is located at /iad/ :

curl -H 'x-FINN-apikey: <API-key>' https://cache.api.finn.no/iad/ | xmllint --format - //with some formatting this time

Take a look at the search workspace :

<atom:title>searches</atom:title>

Here you will find links to all the searches available on www.finn.no. Find a search that is relevant to you, e.g.:

https://cache.api.finn.no/iad/search/realestate-homes
https://cache.api.finn.no/iad/search/car-norway

3. Developing against REST APIs

By now you probably asked yourself "what is the most convenient way to browse the APIs?". Simply pasting the URL in the address bar of the browser will not do it in this case, as you need the custom header. You may not prefer working with a terminal window, or you might not have one (with curl installed) available. There are many tools available that may assist you in doing a HTTP GET with a custom header.

If we were to recomend one, it would be the Dev HTTP Client for Chrome (google it). There are several similar browser plugins, but this one works fine to our experience.

From now on, lets skip that curl stuff and just refer to the URLs instead.

4. Lets do a search

So, now you have some browser plugin or another tool set up and you want to get some real data.

Lets start by doing a search. If you are reading this, your API-key is probably limited to one specific advertiser (that is, a real-estate agent, car dealer etc.). In that case you always need the query parameter orgId when doing a search : 

https://cache.api.finn.no/iad/search/realestate-homes?orgId=<your_orgId>

Note that orgId is a FINN specific id. It is not equal to Organisasjonsnummer.

The response is an Atom feed. Take note of the filters part at the top, the search entries at the bottom and the search description resources.

E.g. if you want to get 100 results in Oslo sorted by "Prisant lav-høy" you need: 

https://cache.api.finn.no/iad/search/realestate-homes?orgId=<your_orgId>&rows=100&location=0.20061&sort=2

5. Get a complete ad

For each result item you get some basic data that is typically presented in a result-view. But you want all available data for one ad. You get that by following the link to the ad: 

<entry>
   ...
   <link href="https://api.finn.no/iad/ad/realestate-homes/<adId>" rel="self"/>
   ....
</entry>

This was a quick introduction.

Continue to the PHP demo client in GitHub.

© 1996 - 2022 FINN.no AS