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), i.e. YYYY-MM-DDTHH:MM:SSZ
• yyyy-mm-dd

In addition, today (for start or end of today) and now (for the exact current timestamp) can be used in either parameter to get current events.

Example:

event/?start=today&end=2020-12-31

See the result

event/?start=now&end=today

See the result

Event location

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.

Event last modification time

To find events that have changed since you last polled Linkedevents API (to e.g. update your event cache), it is best to use the query parameter last_modified_since. This allows you to only return data that has changed after your last update. You may also include events that have been deleted in the API in the results by using the show_deleted filter. This allows you to update your cache with all added, modified and deleted events without having to fetch *all* future events every time.

Example:

event/?last_modified_since=2020-04-07&show_deleted=True

See the result

Event price

Events may or may not contain the offers field that lists event pricing. To return only free or non-free events, use the query parameteris_free. However, note that from some data sources, no event pricing info is available, so this filter will only return those events which have pricing data available.

Example:

event/?is_free=true

See the result

Event language

To find events that have a set language or event data translated into that language, use the query parameter language. If you only wish to see events that have a set language, use the in_language parameter, and if you only want event data translated to a set language, use the translation parameter.

Supported languages are found at the language endpoint, which also lists which languages have translations available. Currently, translations are supported in fi, sv, en, ru, zh_hans, and ar.

Example:

event/?language=ru

See the result

Event publisher

To find out events that are published by a specific organization, use the query parameter publisher, separating values by commas if you wish to query for several publishers.

Also, it is possible to fetch events under a specific publisher organization hierarchy (say

Event hierarchy

Events in linkedevents may be either standalone events, or they may have super or sub events. There are two types of super events, indicated in the field super_event_type by recurring (repeating events, event series) and umbrella (festivals etc.).

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

umbrella events last for a period and may have different sub_events, including recurring events (i.e. an umbrella festival may have a recurring theater play sub_event, which may have several nights as sub_events.)

Super event type

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

Example:

event/?super_event_type=umbrella,none

See the result

Super event

You may use the query parameter super_event, comma separated, to get all subevents for specific superevents. You may use none if you want all events which have no superevent included.

Example:

event/?super_event=linkedevents:agg-103

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. Please note, however, that including all the resources inlined in *every* event will result in a huge number of duplicate data in the json, making the json very slow to generate and process and causing considerable API load and long response times when too many such requests are made. Therefore, if you are listing the maximum number of events (100) or updating your cache with all events, please consider caching the keyword and location data separately to prevent unnecessary API slowdown and continuous repeated work. Keyword and location data seldom change and are easily fetched from their own endpoints separately.

Example:

event/?include=location,keywords

See the result

Ordering

Default ordering is descending order by -last_modified_time. You may also order results by start_time, end_time, name and duration. Descending order is denoted by adding - in front of the parameter, default order is ascending. For example:

event/?sort=-end_time

See the result

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

Keyword text

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

Example:

keyword/?text=lapset

See the result

Unlike other endpoints, keyword_sets do not support filtering. It is expected that the full result set will remain small enough. Recommended keyword_sets are keskisuomi:event-topics for general categorization and keskisuomi-event:audience for target grouping.

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.

Place text

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

Example:

place?text=tuomiokirkko

See the result

No parent

To find places that have no parent, e.g. cities or municipalities, user query parameter no_parent

Example:

place?no_parent=true

See the result

Is address

To find places that are just addresses, user query parameter is_address

Example:

place?is_address=true

See the result

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

Can be used to retrieve translations for a single language