API docs by Redocly

Aluekalenteri API (v2)

Download OpenAPI specification:Download

E-mail: tuki@aluekalenteri.fi License: MIT

Aluekalenteri API provides categorized data on events and places using JSON-LD format. Events can be searched by date and location. JSON-LD format is streamlined using include mechanism. API users can request that certain fields are included directly into the result, instead of being hyperlinks to objects. Several fields are multilingual. These are implemented as object with each language variant as property. In this specification each multilingual field has (fi,sv,en) property triplet as example. Terms of Service vary between API instances.

event

Search and Edit events

Return a list of events

Filtering retrieved events

Query parameters can be used to filter the retrieved events by the following criteria.

Event time

Use start and end to restrict the date range of returned events. Any events that intersect with the given date range will be returned.

The parameters start and end can be given in the following formats:

  • ISO 8601 (including the time of day)
  • yyyy-mm-dd

In addition, today can be used as the value.

Example:

event/?start=2014-01-15&end=2014-01-20

See the result

Event location

Bounding box

To restrict the retrieved events to a geographical region, use the query parameter bbox in the format

bbox=west,south,east,north

Where west is the longitude of the rectangle's western boundary, south is the latitude of the rectangle's southern boundary, and so on.

Example:

event/?bbox=21.7267856118,61.4623491897,21.8666842696,61.4623491897

See the result

Specific location

To restrict the retrieved events to a known location(s), use the query parameter location, separating values by commas if you wish to query for several locations.

Location ids are found at the place endpoint, which lists the locations in decreasing number of events found.

Example:

event/?location=pori:4

See the result

Event keywords

To restrict the retrieved events by keyword, use the query parameter keyword, separating values by commas if you wish to query for several keywords.

Keyword ids are found at the keyword endpoint, which lists the keywords in decreasing number of events found.

Example:

event/?keyword=pori:topic:fairs

See the result

Event audience

Audiences are another set of keywords to narrow down the retrieved events. Use the query parameter audience, separating values by commas if you wish to query for several audiences.

Audience ids are found at the keyword endpoint.

Example:

event/?audience=pori:audience:youth

See the result

Event text

To find out events that contain a specific string in any of the text fields, use the query parameter text.

Example:

event/?text=jazz

See the result

Event hierarchy

Events in linkedevents may be either standalone events, or they may have super or sub events. There is one type of super event, indicated in the field super_event_type by recurring (repeating events, event series).

recurring events last for a period and have sub_events that all have similar data, but different dates.

Super event type

You may use the query parameter super_event_type to get only super events of specific types (recurring, none). You may use none if you want non-super events included.

Example:

event/?super_event_type=recurring

See the result

event/?super_event_type=none

See the result

Getting detailed data

In the default case, keywords, locations, and other fields that refer to separate resources are only displayed as simple references.

If you want to include the complete data from related resources in the current response, use the keyword include. For example:

For including sub events, use include=sub_events. 

event/?include=location,keywords,audience

See the result

Ordering

Default ordering is without specified sort parameters events are sorted by following logic:

  • 1. First comes events starting between today and two days after tomorrow sorted descending by start_time
  • 2. Next comes events starting/started outside of today and two days after tomorrow and have not ended yet sorted descending by end_time
  • 3. Last comes events that have already ended sorted descending by end_time
Allowed sort parameters are last_modified_time, start_time, end_time, name, duration, or date_published. You can reverse the desired sorter by prefixing it with a hyphen (-). For example:

event/?sort=end_time

See the result

Authorizations:
None
query Parameters
include
Array of strings

Embed given reference-type fields directly into the response, otherwise they are returned as URI references.

text
string

Search (case insensitive) through all multilingual text fields (name, description, short_description, info_url) of an event (every language). Multilingual fields contain the text that users are expected to care about, thus multilinguality is useful discriminator.

last_modified_since
string <dateTime>

Search for events that have been modified since or at this time.

start
string <date-time>

Search for events beginning or ending after this time. Dates can be specified using ISO 8601 ("2016-01-12") and additionally "today".

end
string <date-time>

Search for events beginning or ending before this time. Dates can be specified using ISO 8601 ("2016-01-12") and additionally "today".

bbox
Array of strings = 4 items

Search for events that are within this bounding box. Decimal coordinates are given in order west, south, east, north. Period is used as decimal separator.

data_source
string

Search for events that come from the specified source system

location
Array of integers

Search for events in given locations as specified by id. Multiple ids are separated by comma

division
string

You may filter places by specific OCD division id, or by division name. The latter query checks all divisions with the name, regardless of division type. NOTE: Not in use in Aluekalenteri API

keyword
string

Search for events with given keywords as specified by id. Multiple ids are separated by comma

audience
string

Search for events with given audience (special type of keyword) as specified by id. Multiple ids are separated by comma

super_event_type
string
Enum: "recurring" "none"

Events in linkedevents may be either standalone events, or they may have super or sub events.

min_duration
integer

Search for events that are longer than given time in seconds

max_duration
integer

Search for events that are shorter than given time in seconds

publisher
string

Search for events published by the given organization

sort
string

Sort the returned events in the given order. Possible sorting criteria are 'start_time', 'end_time', 'duration' and 'last_modified_time'. The default ordering is '-last_modified_time'.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Create a new event

Authorizations:
None
Request Body schema: application/json
id
string

consists of source prefix and source specific identifier. These should be URIs uniquely identifying the event, and preferably also well formed http-URLs pointing to more information about the event.

required
object (Place)

Places describe physical locations for events and means for contacting people responsible for these locations. Place definitions come from organizations publishing events (field "publisher") and can thus have slightly different semantics between places sourced from different organizations.

keywords
required
Array of strings <uri>

array of keyword uri references

Array of objects (Languages supported in this API)

the languages spoken or supported at the event

super_event
string

references the aggregate event containing this event

super_event_type
string

If the event has sub_events, describes the type of the event. Current options are 'none' and 'recurring'. 'recurring' means a repeating event.

event_status
string

As defined in schema.org/Event. Postponed events do not have a date set, rescheduled events have been moved to different date.

publication_status
required
string

Only available in POST/PUT. Specifies whether the event should be published in the API ('public') or not ('draft').

Array of objects (Links to related information)

See external link definition

Array of objects (Price offers)

See offer definition

sub_events
Array of strings

for aggregate events this contains references to all sub events. Usually this means that the sub events are part of series. The field 'super_event_type' tells the type of the aggregate event.

custom_data
string

Key value field for custom data.

required
object

Short descriptive name for the event, recommended limit: 80 characters

Array of objects (Image)
created_time
string <date-time>

Creation time for the event entry.

last_modified_time
string <date-time>

Time this event was modified in the datastore behind the API (not necessarily in the originating system)

object

Link (URL) to a page with more information about event

object

Description for the event, several chapters

object

Short description for the event, recommended limit 140 characters

date_published
string <date-time>

Date this event is free to be published

object

organization responsible for the practical implementation of the event

object

Unstructured extra info about location (like "eastern door of railway station")

start_time
required
string <date-time>

Time the event will start

end_time
string <date-time>

Time the event will end

Array of objects (Keyword)
data_source
string

Unique identifier (URI)for the system from which this event came from, preferably URL with more information about the system and its policies

created_by
string

Which API user created this keyword

last_modified_by
string

Which API user most recently edited this keyword

publisher
string

Organization responsible for this event record.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "keywords": [],
  • "in_language": [
    ],
  • "super_event": "string",
  • "super_event_type": "string",
  • "event_status": "string",
  • "publication_status": "string",
  • "external_links": [
    ],
  • "offers": [
    ],
  • "sub_events": [
    ],
  • "custom_data": "string",
  • "name": {
    },
  • "images": [
    ],
  • "created_time": "2019-08-24T14:15:22Z",
  • "last_modified_time": "2019-08-24T14:15:22Z",
  • "info_url": {
    },
  • "description": {
    },
  • "short_description": {
    },
  • "date_published": "2019-08-24T14:15:22Z",
  • "provider": {
    },
  • "location_extra_info": {
    },
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "audience": [
    ],
  • "data_source": "string",
  • "created_by": "string",
  • "last_modified_by": "string",
  • "publisher": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "keywords": [],
  • "in_language": [
    ],
  • "super_event": "string",
  • "super_event_type": "string",
  • "event_status": "string",
  • "publication_status": "string",
  • "external_links": [
    ],
  • "offers": [
    ],
  • "sub_events": [
    ],
  • "custom_data": "string",
  • "name": {
    },
  • "images": [
    ],
  • "created_time": "2019-08-24T14:15:22Z",
  • "last_modified_time": "2019-08-24T14:15:22Z",
  • "info_url": {
    },
  • "description": {
    },
  • "short_description": {
    },
  • "date_published": "2019-08-24T14:15:22Z",
  • "provider": {
    },
  • "location_extra_info": {
    },
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "audience": [
    ],
  • "data_source": "string",
  • "created_by": "string",
  • "last_modified_by": "string",
  • "publisher": "string"
}

Retrieve single event by id

Authorizations:
None
path Parameters
id
required
string

Event identifier as defined in event schema

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "keywords": [],
  • "in_language": [
    ],
  • "super_event": "string",
  • "super_event_type": "string",
  • "event_status": "string",
  • "publication_status": "string",
  • "external_links": [
    ],
  • "offers": [
    ],
  • "sub_events": [
    ],
  • "custom_data": "string",
  • "name": {
    },
  • "images": [
    ],
  • "created_time": "2019-08-24T14:15:22Z",
  • "last_modified_time": "2019-08-24T14:15:22Z",
  • "info_url": {
    },
  • "description": {
    },
  • "short_description": {
    },
  • "date_published": "2019-08-24T14:15:22Z",
  • "provider": {
    },
  • "location_extra_info": {
    },
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "audience": [
    ],
  • "data_source": "string",
  • "created_by": "string",
  • "last_modified_by": "string",
  • "publisher": "string"
}

Update an event

Events can be updated if the user has appropriate access permissions. The original implementation behaves like PATCH, ie. if some field is left out from the PUT call, its value is retained in database. In order to ensure consistent behaviour, users should always supply every field in PUT call.

Authorizations:
None
path Parameters
id
required
string

Identifier for the event to be updated

Request Body schema: application/json

Event object that should replace the existing event, note that some implementations may retain unspecified fields at their original values.

id
string

consists of source prefix and source specific identifier. These should be URIs uniquely identifying the event, and preferably also well formed http-URLs pointing to more information about the event.

required
object (Place)

Places describe physical locations for events and means for contacting people responsible for these locations. Place definitions come from organizations publishing events (field "publisher") and can thus have slightly different semantics between places sourced from different organizations.

keywords
required
Array of strings <uri>

array of keyword uri references

Array of objects (Languages supported in this API)

the languages spoken or supported at the event

super_event
string

references the aggregate event containing this event

super_event_type
string

If the event has sub_events, describes the type of the event. Current options are 'none' and 'recurring'. 'recurring' means a repeating event.

event_status
string

As defined in schema.org/Event. Postponed events do not have a date set, rescheduled events have been moved to different date.

publication_status
required
string

Only available in POST/PUT. Specifies whether the event should be published in the API ('public') or not ('draft').

Array of objects (Links to related information)

See external link definition

Array of objects (Price offers)

See offer definition

sub_events
Array of strings

for aggregate events this contains references to all sub events. Usually this means that the sub events are part of series. The field 'super_event_type' tells the type of the aggregate event.

custom_data
string

Key value field for custom data.

required
object

Short descriptive name for the event, recommended limit: 80 characters

Array of objects (Image)
created_time
string <date-time>

Creation time for the event entry.

last_modified_time
string <date-time>

Time this event was modified in the datastore behind the API (not necessarily in the originating system)

object

Link (URL) to a page with more information about event

object

Description for the event, several chapters

object

Short description for the event, recommended limit 140 characters

date_published
string <date-time>

Date this event is free to be published

object

organization responsible for the practical implementation of the event

object

Unstructured extra info about location (like "eastern door of railway station")

start_time
required
string <date-time>

Time the event will start

end_time
string <date-time>

Time the event will end

Array of objects (Keyword)
data_source
string

Unique identifier (URI)for the system from which this event came from, preferably URL with more information about the system and its policies

created_by
string

Which API user created this keyword

last_modified_by
string

Which API user most recently edited this keyword

publisher
string

Organization responsible for this event record.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "keywords": [],
  • "in_language": [
    ],
  • "super_event": "string",
  • "super_event_type": "string",
  • "event_status": "string",
  • "publication_status": "string",
  • "external_links": [
    ],
  • "offers": [
    ],
  • "sub_events": [
    ],
  • "custom_data": "string",
  • "name": {
    },
  • "images": [
    ],
  • "created_time": "2019-08-24T14:15:22Z",
  • "last_modified_time": "2019-08-24T14:15:22Z",
  • "info_url": {
    },
  • "description": {
    },
  • "short_description": {
    },
  • "date_published": "2019-08-24T14:15:22Z",
  • "provider": {
    },
  • "location_extra_info": {
    },
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "audience": [
    ],
  • "data_source": "string",
  • "created_by": "string",
  • "last_modified_by": "string",
  • "publisher": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "keywords": [],
  • "in_language": [
    ],
  • "super_event": "string",
  • "super_event_type": "string",
  • "event_status": "string",
  • "publication_status": "string",
  • "external_links": [
    ],
  • "offers": [
    ],
  • "sub_events": [
    ],
  • "custom_data": "string",
  • "name": {
    },
  • "images": [
    ],
  • "created_time": "2019-08-24T14:15:22Z",
  • "last_modified_time": "2019-08-24T14:15:22Z",
  • "info_url": {
    },
  • "description": {
    },
  • "short_description": {
    },
  • "date_published": "2019-08-24T14:15:22Z",
  • "provider": {
    },
  • "location_extra_info": {
    },
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "audience": [
    ],
  • "data_source": "string",
  • "created_by": "string",
  • "last_modified_by": "string",
  • "publisher": "string"
}

filter

Search for keywords and places for filtering events

Returns a list of keywords used for describing events

Using the keyword endpoint

Here, categories for events are listed. Events in each category can be found at the event endpoint using the query parameter keyword. The common keywords used in all events originate from keywords added to Satakunta Events system, hence the format pori:topics:fairs.

Keyword text

To find keywords that contain a specific string, use the query parameter text.

Example:

keyword/?text=kulttuuri

See the result

Keyword source

Will restrict keywords to a specific data source.

Example:

keyword/?data_source=pori

See the result

Ordering

Default ordering is decreasing order by the number of events found. You may also order results by name.

Example:

keyword/?sort=name

See the result

Showing all keywords

By default, only those keywords which have listed events are displayed. You may display keywords with zero n_events with the query parameter show_all_keywords.

Authorizations:
None
query Parameters
page
integer

request particular page in paginated results

page_size
integer [ 1 .. 300 ]
Default: 30

request that server delivers page_size results in response

include
Array of strings

Embed given reference-type fields directly into the response, otherwise they are returned as URI references.

show_all_keywords
boolean

Show all keywords, including those that are not associated with any events. Otherwise such keywords are hidden. When show_all_keywords is specified, no other filter is applied, except "filter" (match for keywords beginning with string)

data_source
string

Search for keywords (note: NOT events) that come from the specified data source (see data source in keyword definition). The data sources are (not all of these data sources have keywords):

* finna
* kankaanpaa
* menoinfo
* pori
* se
* system
* visitpori
text
string

Search for keywords (note: NOT events) that contain the given string. This applies even when show_all_keywords is specified.

sort
string

Sort the returned keywords in the given order. Possible sorting criteria are 'n_events', 'id', 'name', 'data_source'. The default ordering is '-data_source', '-n_events'.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Return information for single keyword

Authorizations:
None
path Parameters
id
required
string

Same as id in keyword schema

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": {
    },
  • "images": [
    ],
  • "origin_id": "string",
  • "created_time": "2019-08-24T14:15:22Z",
  • "last_modified_time": "2019-08-24T14:15:22Z",
  • "aggregate": true,
  • "data_source": "string",
  • "created_by": "string",
  • "last_modified_by": "string",
  • "alt_labels": [
    ]
}

Return as list of keyword_sets for grouping keywords

Unlike other endpoints, keyword_sets do not support filtering. It is expected that the full result set will remain small enough.

Authorizations:
None
query Parameters
page
integer

request particular page in paginated results

page_size
integer [ 1 .. 300 ]
Default: 30

request that server delivers page_size results in response

include
Array of strings

Embed given reference-type fields directly into the response, otherwise they are returned as URI references.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Return information about single keyword_set

Authorizations:
None
path Parameters
id
required
string

Same as id in keyword_set schema. For example, to fetch all keywords for Pori calendar, use id pori:topics. This will list all keywords with @id-resource address. To include details of each keyword, use include=keywords parameter.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "origin_id": "string",
  • "created_time": "2019-08-24T14:15:22Z",
  • "last_modified_time": "2019-08-24T14:15:22Z",
  • "data_source": "string",
  • "last_modified_by": "string",
  • "usage": "any",
  • "organization": "string",
  • "keywords": [
    ]
}

Returns list of places used for describing events

Using the place endpoint

Here, locations for events are listed. Events in each location can be found at the event endpoint using the query parameter location. Locations are pre-added to the system.

Place text

To find places that contain a specific string, use the query parameter text.

Example:

place/?text=pori

See the result

Different levels of places

Places (or locations) contain some hierarchy. There are so-called top-level areas (such as cities), which have no parent place. In addition there are subareas, such as city centers, and then specific street addresses. Subareas and street addresses always have a parent place. In addition, street addresses have a field is_address set to true, whereas top-level areas and subareas have it set to false. You can use the filters parent_id or no_parent (true | false) and is_address (true | false) to narrow down on top-level areas, subareas, and street addresses as needed. For example, to fetch subareas you could use:

place/?is_address=false&no_parent=false

See the result

District

Not in use in Aluekalenteri API

Ordering

Default ordering is decreasing order by the number of events found. You may also order results by name, street_address or postal_code. For example:

place/?sort=name

See the result

Place source

Will restrict places to a specific data source.

Example:

place/?data_source=pori

See the result

Showing all places

By default, only those locations which have listed events are displayed. You may display locations with zero n_events with the query parameter show_all_places.

Authorizations:
None
query Parameters
page
integer

request particular page in paginated results

page_size
integer [ 1 .. 300 ]
Default: 30

request that server delivers page_size results in response

parent_id
string

See method description above for notes about is_address, no_parent, and parent_id

is_address
boolean

See method description above for notes about is_address, no_parent, and parent_id

no_parent
boolean

See method description above for notes about is_address, no_parent, and parent_id

show_all_places
boolean

Show all places, including those that are not hosting any events. Otherwise such places are hidden. When show_all_places is specified, no other filter is applied.

division
string

You may filter places by specific OCD division id, or by division name. The latter query checks all divisions with the name, regardless of division type. NOTE: Not in use in Aluekalenteri API

sort
string

Sort the returned places in the given order. Possible sorting criteria are 'n_events', 'id', 'name', 'street_address' and 'postal_code'. The default ordering is '-n_events'.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Return information for single place

Authorizations:
None
path Parameters
id
required
string

Id as defined in place model

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "custom_data": [
    ],
  • "name": {
    },
  • "images": [
    ],
  • "origin_id": "string",
  • "created_time": "2019-08-24T14:15:22Z",
  • "last_modified_time": "2019-08-24T14:15:22Z",
  • "info_url": {
    },
  • "description": {
    },
  • "position": {
    },
  • "email": "string",
  • "telephone": {
    },
  • "contact_type": "string",
  • "street_address": {
    },
  • "address_locality": {
    },
  • "address_region": "string",
  • "postal_code": "string",
  • "post_office_box_num": "string",
  • "address_country": "string",
  • "deleted": true,
  • "data_source": "string",
  • "publisher": "string"
}

language

Get supported languages

Return a list of languages used for describing events

The returned list describes languages used for describing events in this Linked events instance

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Return information for single language

Can be used to retrieve translations for a single language

Authorizations:
None
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": {
    }
}

image

Upload images

Create a new image

There are two ways to create an image object. The image file can be posted as a multipart request, but the endpoint also accepts a simple JSON object with an external url in the url field. This allows using external images for events without saving them on the API server.

Authorizations:
None
Request Body schema: multipart/form-data
image_file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "name": {
    },
  • "publisher": "string",
  • "created_time": "2019-08-24T14:15:22Z",
  • "last_modified_time": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "last_modified_by": "string",
  • "url": "string",
  • "cropping": "string",
  • "license": "string"
}