XML

Most of Suomi.fi content is available in a machine readable format. XML is the default format in the Suomi.fi REST API but the contents are also available in JSON for easier use in browser-based applications.

The query URL of the API is www.suomi.fi/rest/. Adding formal terms to the URL lets you retrieve specific contents. The default content language is Finnish. For contents in English or Swedish, just add the code "en" or "sw" to the query URL. The URL for English contents is www.suomi.fi/rest/en/.

An "apikey" parameter and your apikey code are required with every query. To get your apikey code, use the form on the page (in Finnish) REST apikeyn tilaus.

Below are some examples of how to use the API.

Suomi.fi service categories

Suomi.fi service categories correspond to the categories in the Services by topic section of Suomi.fi.

A listing of all service categories can be retrieved with these queries:
http://www.suomi.fi/rest/services/?apikey=xxxx (Finnish)
http://www.suomi.fi/rest/sv/services/?apikey=xxxx (Swedish)
http://www.suomi.fi/rest/en/services/?apikey=xxxx (English)

Adding service category name to the query URL will yield detailed data for the sub-categories in each service category, along with keywords and page content in html. For example, data in the English language version of the Housing and Construction category can be retrieved with the query:
http://www.suomi.fi/rest/en/services/housing_and_construction/?apikey=xxxx

There are several content types within the service categories. These include links, forms and laws. For example, nationwide content for these content types in the Housing and construction category can be retrieved with:
http://www.suomi.fi/rest/services/housing_and_construction/links/?apikey=xxxx
http://www.suomi.fi/rest/services/housing_and_construction/forms/?apikey=xxxx
http://www.suomi.fi/rest/services/housing_and_construction/laws/?apikey=xxxx

Municipal information can be retrieved by adding the municipality's name to the query. For example, Helsinki's service links in the Housing and construction category can be retrieved with:
http://www.suomi.fi/rest/services/housing_and_construction/links/helsinki/?apikey=xxxx

Regions and municipalities

Suomi.fi includes an up to date listing of Finland's regions and municipalities. For example, the query URL for the listing of municiplaities in the Uusimaa region is:
http://www.suomi.fi/rest/counties/uusimaa/?apikey=xxxx

Data on the Vihti municipality and their services can be retrieved with:
http://www.suomi.fi/rest/municipalities/vihti/?apikey=xxxx

Other query parameters

A selection of parameters added to a query URL can be used to define the format, filtering and order of the retrieved data. for example, service links for Housing and construction in JSON are retrieved with:
http://www.suomi.fi/rest/services/housing_and_construction/links?return=json/?apikey=xxxx

All service links added since August 10, 2010, can be retrieved with:
http://www.suomi.fi/rest/links?start_date=2010-08-01/?apikey=xxxx

All service links added before August 10, 2010, can be retrieved with:
http://www.suomi.fi/rest/links?end_date=2010-07-31/?apikey=xxxx

Query results can be ordered according to title (sort=title; this is the default option), date (sort=date) or popularity (sort=popularity, only applicable to links and forms). For example, all service links in alphabetical order are retrieved with:
http://www.suomi.fi/rest/links?sort=title/?apikey=xxxx

All service links sorted by date, oldest to latest, are retrieved with:
http://www.suomi.fi/rest/links?sort=date/?apikey=xxxx

The Sort-parameter can be further defined with the reverse=true parameter that turns the sorting order around. For example, links sorted by date, from latest to oldest, are retrieved with:
http://www.suomi.fi/rest/links?sort=date&reverse=true/?apikey=xxxx

The number of query results can be limited using the limit=xx parameter. If you only want the ten latest links, use:
http://www.suomi.fi/rest/links?sort=date&reverse=true&limit=10/?apikey=xxxx

Note that the Limit parameter always comes last, so it can only limit the query results defined by other parameters.

The ten most popular links are retrieved with:
http://www.suomi.fi/rest/links?sort=popularity&reverse=true&limit=10/?apikey=xxxx

Summary of all query types (for Finnish content query URL structure; to get English content, see language code instructions above):

Service categories

www.suomi.fi/rest/services/?apikey=xxxx
www.suomi.fi/rest/services/{service_category}/?apikey=xxxx
www.suomi.fi/rest/services/{service_category|oid}/forms/?apikey=xxxx
www.suomi.fi/rest/services/{service_category|oid}/forms/{kunta|oid}/?apikey=xxxx
www.suomi.fi/rest/services/{service_category|oid}/links/?apikey=xxxx
www.suomi.fi/rest/services/{service_category|oid}/links/{kunta|oid}/?apikey=xxxx
www.suomi.fi/rest/services/{service_category|oid}/laws/?apikey=xxxx

Regions

www.suomi.fi/rest/counties/?apikey=xxxx
www.suomi.fi/rest/counties/{region|oid}/?apikey=xxxx

Municipalities

www.suomi.fi/rest/municipalities/?apikey=xxxx
www.suomi.fi/rest/municipalities/{municipality|oid}/?apikey=xxxx
www.suomi.fi/rest/municipalities/{municipality|oid}/forms/?apikey=xxxx
www.suomi.fi/rest/municipalities/{municipality|oid}/links/?apikey=xxxx

Organizations

www.suomi.fi/rest/organizations/?apikey=xxxx
www.suomi.fi/rest/organizations/{organization|oid}/?apikey=xxxx
www.suomi.fi/rest/organizations/{organization|oid}/links/?apikey=xxxx

Service links

www.suomi.fi/rest/links/?apikey=xxxx
www.suomi.fi/rest/links/{organization|oid}/?apikey=xxxx
www.suomi.fi/rest/links/{servicecategory|oid}/?apikey=xxxx
www.suomi.fi/rest/links/{oid}/?apikey=xxxx

Forms

www.suomi.fi/rest/forms/?apikey=xxxx
www.suomi.fi/rest/forms/{municipality|oid}/?apikey=xxxx
www.suomi.fi/rest/forms/{service_category|oid}/?apikey=xxxx
www.suomi.fi/rest/forms/{oid|form_identifier}/?apikey=xxxx

Laws

www.suomi.fi/rest/laws/?apikey=xxxx
www.suomi.fi/rest/laws/{service_category|oid}/?apikey=xxxx
www.suomi.fi/rest/laws/{finlex_identifier|oid}/?apikey=xxxx

Keywords

www.suomi.fi/rest/keywords/?apikey=xxxx
www.suomi.fi/rest/keywords/{keywordid|langversionid}/?apikey=xxxx

News

www.suomi.fi/rest/news/?apikey=xxxx
www.suomi.fi/rest/news/{oid}/?apikey=xxxx

On a web page that uses Suomi.fi content, the source should be mentioned, for example like this: "This information is retrieved from the Suomi.fi portal produced in the State Treasury."

The Suomi.fi team is happy to receive information on any web page or site that uses the Suomi.fi REST.