Technical documentation for implementers of integrations
PTV is currently undergoing an architectural reform, which will include the release of API version 12 and, after a transition period, the shutdown of the version 11. Please take this change into account when planning your new integration!
API versions of the Finnish Service Catalogue
Currently, the API version 11 is in use. No new integrations should be added to API version 11.
API version | 2025 | 2026 | 2027 |
|---|---|---|---|
API version 11 | supported | supported | to be phased out in spring 2027 (indicative) |
API version 12 | Methods for the OUT interface production environment (beta version) are implemented | IN interface methods to be implemented in spring 2027 (indicative) |
Basic information from the FSC interface
The Finnish Service Catalogue has an open REST/JSON interface. The data is made available to be used freely with the CC0 licence, which means that the data can be utilised without restrictions. However, the Digital and Population Data Services Agency requires that each organisation implementing the integration report the integration and submit their contact details to the address ptv-tuki@dvv.fi to enable communication about service disruptions.
The OUT interface makes it possible to retrieve data without logging in or an access licence.
More information for implementers of the OUT integration
Data from another system can be imported to the FSC through the IN interface. However, a separate access licence is required for this.
More information for implementers of the IN integration
The map coordinate standard used in the location data of the organisation and the service location is EPSG 3067.
The most recent interface version must always be deployed when implementing a new integration.
Data model
The Finnish Service Catalogue contains customer-oriented descriptions of services and the details of the service channels related to them, as well as the connection information between them. It is also possible to retrieve information about organisations that have described the services. Before starting to implement the integration, familiarise yourself carefully with the FSC’s concept and data model.
Some of the data in the Finnish Service Catalogue is descriptions in text form and intended for human readers, and some is metadata.
FSC production Swagger
The OUT and IN-interface methods can be found in SwaggerOpens in a new window.. The methods have been grouped into eight different themes:
- CodeList/Code lists
- Common/Common
- Connection/Connection
- GeneralDescription/General description
- Organization/Organisation
- Service/Service
- ServiceChannel/Service channel
- and ServiceCollection/Service collection.
GET methods enable data retrieval, POST methods addition of new data and PUT methods updates of these data. A user permit for the IN interface is required for using the POST and PUT methods.
It is possible to also retrieve information on services on the basis of area information, target group, service class, service type and industrial class.
More specific use of the methods is instructed in Swagger.
Some of the methods are restricted to the Digital and Population Data Services Agency’s own use and some to the ASTI system.
FSC’s source code
The FSC’s source code is currently not available in Github. If you need the FSC code, request it from the following address: ptv-tuki@dvv.fi.