Additional information for implementers of the OUT-integration

1. Retrieve the organisations

You can use the GET Organization method to retrieve a list of all organisations with published services and service channels in Suomi.fi Finnish Service Catalogue. The method returns the names and IDs of the organisations.

2. Retrieve the organisations’ services

When you know the ID of an organisation, you can retrieve a list of the organisation's services by using the GET Organization/{id} method. The method returns the names and IDs of the organisation’s services.

3. Retrieve the data of the services

Next, you can retrieve the data of the organisation’s services by using the service's ID returned in the organisation’s details.

When services do not have a general description

you can retrieve

• all data of an individual service with the GET Service/{id} method
• or all data of several services with the GET Service/list method.

When services have a general description

Some services have a general description in their background. General descriptions have been drawn up for municipalities, wellbeing services counties, regional services for companies, and parishes to use.

It is not mandatory to fetch the information on the general descriptions, but they contain useful background information about the services.

You can retrieve

• the data of an individual service, including its general description, with the serviceWithGD/{id} method or
• all details of several services, including their general descriptions, with the GET Service/serviceWithGD/list method.

4. Retrieve the data of all service channels connected to the services

The name and ID details of the service channels connected to the service are returned in the data of the service.

You can retrieve

• all data of an individual service channel with the GET ServiceChannel {id} method or
• the data several service channels with the GET ServiceChannel/list method.

Note! The name of an e-service channel and a web page service channel must be described so that it can be used as link text pointing to the service channel’s URL. When you use the service channel’s URL, use the channel’s name as the link text. Do not display only the URL, as it is neither descriptive nor accessible.

• Several methods are available for limiting the data to be retrieved. The following are examples of the most important ones:

Limiting service information

You can limit the list of services on the basis of area information. The possible definitions are municipality (Municipality), region (Province) and wellbeing services county (WellbeingServiceCounties).

/api/v11/Service/list/area/{area}/code/{code} returns all services with area information in accordance with the definition as well as the names and IDs of the service channels related to them.

It is also possible to limit services by using the following values:

• service class (GET Service/serviceClass)
• target group (GET Service/targetGroup)
• service type (GET Service/type)
• sector of the service (GET Service/industrialClass)

You will find the required retrieval parameters in the following file.

Code lists used in the FSC, Digital and Population Data Services Agency (XLSX, 14.07 kB)Opens in a new window.

Unfortunately, no retrievals combining several parameters are available.

Limiting service channel information

The list of service channels may also be limited on the basis of area information. The possible definitions are municipality (Municipality), region (Province) and wellbeing services county (WellbeingServiceCounties).

/api/v11/ServiceChannel/list/area/{area}/code/{code} returns all services with area information in accordance with the definition as well as the names and IDs of the services related to them.

It is also possible to also limit service channels according to the type of service channel.

The /api/v11/ServiceChannel/type/{type} method makes it possible to restrict the retrieval according to the type of service channel. The permitted values are Echannel (online service), WebPage (website), PrintableForm (printable form), Phone (phone service) and ServiceLocation (service location).

Limiting the details of organisations

The list of returned organisations can also be limited on the basis of area information. The possible definitions are municipality (Municipality), region (Province) and wellbeing services county (WellbeingServiceCounties).

• GET Organisation/area/{area}/code/{code}) returns all published organisations that have area information in accordance with the definition.
• GET Organization/list returns all organisations that have area information in accordance with the definition and the names and IDs of the services of all these organisations. The method also returns services in which the retrieved organisation is another organisation responsible for the service (roleType: OtherResponsible).

Many methods make it possible to restrict the retrieval with the modification date and retrieve contents that have been changed

• after the given date (date)
• before the given date (dateBefore) or
• between specific dates.

This is practicable when you only want to retrieve the data that have changed after the previous data retrieval.

The time in the PTV data has a different precision than in the parameters: in the FSC data, the editing time is reported with millisecond precision, but the parameters only have the option of limiting it with the precision of seconds.

Details of organisations

1. Use the following method to retrieve the new and updated organisations

GET api/v11/Organization?date=yyyy-mm-ddThh:mm:ss

• The list of the organisations’ IDs and names is displayed.
• NOTE! The method returns the number of pages in the field (pagecount). If its value is > 1, repeat the retrieval for each page: api/v11/Organization?date=yyyy-mm-ddThh:mm:ss&page=x.
• Save the IDs.
• Use the following method to retrieve the full details of the organisations in groups of 100 IDs:/api/v11/Organization/list?guids=id1,id2,id3,id4.
• Add the new organisations to your own database and update the details of the changed organisations.

2. Use the following method to retrieve the deleted organisations:

GET /api/v11/Organization?status=archived&date=yyyy-mm-ddThh:mm:ss

• The list of the organisations’ names and IDs is displayed.
• Delete the organisations from your own database.

3. Use the following method to retrieve the organisations restored to draft status:

GET /api/v11/Organization?status=withdrawn&date=yyyy-mm-ddThh:mm:ss

• The list of the organisations’ names and IDs is displayed.
• Delete the organisations from your own database.

Service details

1. Use the following method to retrieve the new and updated services

GET api/v11/Service?date=yyyy-mm-ddThh:mm:ss

• The list of the service’s IDs and names is displayed.
• NOTE! The method returns the number of pages in the field (pagecount). If its value is > 1, repeat the retrieval for each page.
• Save the IDs.
• Use the following method to retrieve full service details in groups of 100 IDs:/api/v11/Service/list?guids=id1,id2,id3,id4.
• Add the new services to your own database and update the details of the changed services.

2. Use the following method to retrieve the deleted services:

GET /api/v11/Services?status=archived&date=yyyy-mm-ddThh:mm:ss

• The list of the services’ names and IDs is displayed.
• Delete the services from your own database.

3. Use the following method to retrieve the services restored to draft status:

GET /api/v11/Service?status=withdrawn&date=yyyy-mm-ddThh:mm:ss

• The list of the services’ names and IDs is displayed.
• Delete the services from your own database.

Details of service channels

1. Use the following method to retrieve the new and updated service channels:

GET api/v11/ServiceChannel?date=yyyy-mm-ddThh:mm:ss

• The list of the service channels’ IDs and names is displayed.
• NOTE! The method returns the number of pages in the field (pagecount) If its value is > 1, repeat the retrieval for each page.
• Save the IDs.
• Use the following method to retrieve full service channel details in groups of 100 IDs:/api/v11/Service/list?guids=id1,id2,id3,id4.
• Add the new service channels to your own database and update the details of the changed service channels.

2. Use the following method to retrieve the deleted service channels:

GET /api/v11/ServicesChannel?status=archived&date=yyyy-mm-ddThh:mm:ss

• The list of the service channels’ names and IDs is displayed.
• Delete the service channels from your own database.

3. Use the following method to retrieve the service channels restored to draft status:

GET /api/v11/ServiceChannel?status=withdrawn&date=yyyy-mm-ddThh:mm:ss

• The list of the service channels’ names and IDs is displayed.
• Delete the service channels from your own database.

Names of service time fields and their purpose

Normal opening hours

The section ‘Normal opening hours: days of the week’ describes the most common opening hours of the service channel. Opening hours can be defined for the selected day* (00.00–24.00), in other words, the opening hours cannot continue into the following day. The opening hours of one day can be divided into separate periods of opening hours. There may be a total of four periods (Example 1).

*) All days of the week can be selected (Monday–Sunday)

‘Always open (24/7)’ or ‘Open by appointment’ can also be selected as opening hours in the ‘Normal opening hours: days of the week’ section.

Opening hours can be either valid until further notice or valid between dates. In the Valid between dates option, the user gives the time period during which the opening hours are valid. Both have the above-mentioned options (days of the week, 24/7, by appointment).

1) valid until further notice - on Tuesday and Wednesday

Opening hours:
• Tuesday 8.00-12.00, 13.00–14:.00, 15.00–16.00 and 17.00–18.00
• Wednesday 9.00–16.30
• Thursday 00.00–24.00 ← Note! For 24.00, the value 00.00 is entered in the interface
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 1: valid until further notice ",
"language": "en"
}
],
"openingHour": [
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "08:00:00",
"to": "12:00:00"
},
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "13:00:00",
"to": "14:00:00"
},
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "15:00:00",
"to": "16:00:00"
},
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "17:00:00",
"to": "18:00:00"
},
{
"dayFrom": "Wednesday",
"dayTo": null,
"from": "09:00:00",
"to": "16:30:00"
},
{
"dayFrom": "Thursday",
"dayTo": null,
"from": "00:00:00",
"to": "00:00:00"
}
]
}

2) valid for a time period - on Wednesday and Thursday

Time period:
• 8 December 2023–10 December 2023
Opening hours:
• Wednesday 9.30–16.30
• Thursday 9.30–16.30
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": "2023-12-08T00:00:00",
"validTo": "2023-12-10T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 2: valid for a time period",
"language": "en"
}
],
"openingHour": [
{
"dayFrom": "Wednesday",
"dayTo": null,
"from": "09:30:00",
"to": "16:30:00"
},
{
"dayFrom": "Thursday",
"dayTo": null,
"from": "09:30:00",
"to": "16:30:00"
}
]
}

3) valid until further notice - always open (24/7)

Opening hours:
• Always open (24/7)
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": true,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 3: valid until further notice - always open",
"language": "en"
}
],
"openingHour": []
}

4) valid until further notice – open by appointment

Opening hours:
• open only by appointment
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": true,
"additionalInformation": [
{
"value": "Test 4SV",
"language": "sv"
},
{
"value": "Test 4EN",
"language": "en"
},
{
"value": "Testi 4: Toistaiseksi voimassa oleva, avoinna ajanvarauksella",
"language": "en"
}
],
"openingHour": []
},

5) valid between dates - always open (24/7)

Time period:
• 3 January 2024–4 January 2024
Opening hours:
• Always open (24/7).
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": "2024-01-03T00:00:00",
"validTo": "2024-01-04T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": true,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 5: valid between dates - always open",
"language": "en"
}
],
"openingHour": []
}

6) valid between dates - open by appointment

Time period:
• 22 December 2023–24 December 2023
Opening hours:
• Open only by appointment
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": "2023-12-22T00:00:00",
"validTo": "2023-12-24T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": true,
"additionalInformation": [
{
"value": "Test 6: valid between dates - open by appointment",
"language": "en"
}
],
"openingHour": []
}

7) valid until further notice - only heading

You can send normal service time information using the only heading field. The date or the opening hours are not mandatory.
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 2A: only heading",
"language": "en"
}
],
"openingHour": []
}
],

Normal opening hours: hours exceeding 24-hour periods (emergency service)

In the ‘Normal opening hours: hours exceeding 24-hour periods’ section, the opening hours of an emergency service -type service channel are described. In this section, the opening hours usually begin on the selected day and continue into the following 24-hour period. The opening hours cannot be divided into separate sections.

*) All days of the week can be selected (Monday–Sunday)

Opening hours can be either valid until further notice or valid between dates. In the Valid between dates option, the user gives the time period during which the opening hours are valid.

1) valid until further notice - from Tuesday to Wednesday

Opening hours:
• from 18.00 on Tuesday to 2.00 on Wednesday
{
"serviceHourType": "OverMidnight",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 7: valid until further notice - from Tuesday to Wednesday",
"language": "en"
}
],
"openingHour": [
{
"dayFrom": "Tuesday",
"dayTo": "Wednesday",
"from": "18:00:00",
"to": "02:00:00"
}
]
}

2) valid between dates - from Wednesday to Friday

Time period:
• 23 December 2023–25 December 2023
Opening hours:
• from 20.00 on Wednesday to 10.00 on Friday
{
"serviceHourType": "OverMidnight",
"validFrom": "2023-12-23T00:00:00",
"validTo": "2023-12-25T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 8: valid between dates - from Wednesday to Friday",
"language": "en"
}
],
"openingHour": [
{
"dayFrom": "Wednesday",
"dayTo": "Friday",
"from": "20:00:00",
"to": "10:00:00"
}
]
},

Exceptional service times

In the ‘Exceptional hours of service’ section, opening hours that deviate from the normal opening hours of the service channel are described. These are usually temporary and a time period is determined for their validity.

The time period for the opening hours may be a day or a longer time period. The option ‘Closed all day’ can also be selected in this section.

1) Day, Time period: 26 December 2023

{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-26T00:00:00",
"validTo": null,
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 9: day",
"language": "en"
}
],
"openingHour": [
{
"dayFrom": null,
"dayTo": null,
"from": "12:00:00",
"to": "15:00:00"
}
]
}

2) Day - closed all day

Time period: 26 December 2023
{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-25T00:00:00",
"validTo": null,
"isClosed": true,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 10: Day - closed all day",
"language": "en"
}
],
"openingHour": []
},

3) Time period, Time period: 24 December 2023–25 December 2023

Opening hours:

Opening hours:
• from 20.00 on Thursday to 10.00 on Friday
{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-24T00:00:00",
"validTo": "2023-12-25T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 11: Time period",
"language": "en"
}
],
"openingHour": [
{
"dayFrom": null,
"dayTo": null,
"from": "20:00:00",
"to": "10:00:00"
}
]
}

4) Time period - closed all day, Time period: 26 December 2023–27 December 2023

Opening hours:

{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-26T00:00:00",
"validTo": "2023-12-27T00:00:00",
"isClosed": true,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 12: Time period - closed all day",
"language": "en"
}
],
"openingHour": []
}