Filtering retrieved events

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

Ongoing local events

Use to quickly access local (municipality level) events that are upcoming or have not ended yet. Combines the search on a number of description, name, and keyword fields. Locality is defined on the basis of MUNIGEO_MUNI value, which is set in the settings file. In the Helsinki case all the events would be retrieved that happen within Helsinki. Comes in two flavors: AND and OR. Use local_ongoing_AND=lapset,musiikki to search for the events with both search terms in the description fields and local_ongoing_OR to search for the events with at least one term mentioned. In case you need to realize a more complicated logic and search for a combination of search terms as in (singing OR vocal) AND (workshop OR training) use local_ongoing_OR_setX parameter, where X is a number.

Examples:

event/?local_ongoing_OR=lapsi,musiikki

See the result

event/?local_ongoing_OR_set1=lapsi,musiikki&local_ongoing_OR_set2=leiri,kurssi

See the result

Ongoing internet events

Use to quickly access internet-based events that are upcoming or have not ended yet. Usage is the same as for local ongoing events, three variations: internet_ongoing_AND, internet_ongoing_OR, and internet_ongoing_OR_setX, Note, that local_ongoing and internet_ongoing are mutually exclusive.

Example:

event/?internet_ongoing_AND=lapsi,musiikki

See the result

All ongoing events

All ongoing events, both internet and local combined. Usage is the same as for local ongoing events: all_ongoing_AND, all_ongoing_OR and all_ongoing_OR_setX

Example:

event/?all_ongoing_AND=lapsi,musiikki

See the result

Internet based

Filter for all the events that happen in the internet, both past and upcoming.

Example:

event/?internet_based=true

See the result

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

You can also use days filter to restrict the date range of returned events. Any events that intersect with the current time and amount of days from current time will be returned.

The parameters start and end cannot be used together with the days parameter.

Example:

event/?days=7

See the result

Event start/end time

Use starts_after, starts_before, ends_after, and ends_before to filter for the events that start and end within certain hours, for example for the ones that start after 17:00 and end before 21:00.

The parameters can be given as:

  • Hours only
  • Hours and minutes separated by a colon

Example:

event/?starts_after=16:30&ends_before=21

See the result

Event duration

Use max_duration to filter for the events that last up to a specified time, or min_duration to filter for the events that last at least a specified amount of time.

The parameters are expressed in format:

  • 86400 or 86400s (24 hours)
  • 180m or 3h (3 hours)
  • 3d (3 days)

Example:

event/?max_duration=3d

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. The default coordinate system is the trusty old EPSG:4326 known from all online maps, and can be overridden with srid parameter.

Example:

event/?bbox=24.9348,60.1762,24.9681,60.1889

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. Most locations originate from the Helsinki service point registry (tprek), hence the format tprek:28473. An easy way to locate service points is to browse servicemap.hel.fi, which uses the same location ids, e.g. servicemap.hel.fi/unit/28473.

Example:

event/?location=tprek:28473

See the result

District

To restrict the retrieved events to city district(s), use the query parameter division, separating values by commas if you wish to query for several divisions.

City of Helsinki neighborhoods (kaupunginosa), districts (peruspiiri) and subdistricts (osa-alue) are supported. Check the divisions on the Helsinki map service.

You may query either by specific OCD division type peruspiiri:malmi, or by division name malmi. The latter query checks all divisions with the name, regardless of division type.

Example:

event/?division=malmi

See the result

Within a distance (or "circle filter")

To restrict the retrieved events to a certain distance from a point, use the query parameters dwithin_origin and dwithin_metres in the format

dwithin_origin=lon,lat&dwithin_metres=distance

Where lon is the longitude of the origin point, lat is the latitude of the origin point, and distance is the radius in metres. Both parameters are required. The default coordinate system is EPSG:4326 and can be overridden with the srid parameter.

Example:

event/?dwithin_origin=24.9348,60.1762&dwithin_metres=1000

See the result

Event category

To restrict the retrieved events by category, use the query parameter keyword, separating values by commas if you wish to query for any of several keywords, or the parameter keyword_AND, if you require all provided values (separated by commas) to be present. Use parameter keyword! if you require all provided values (separated by commas) not to be present.

In case you need to realize a more complicated logic and search for a combination of keywords as in (yso:p1235 OR yso:p1947) AND (yso:p14004 OR yso:p11185) use keyword_OR_setX parameter, where X is a number.

Keyword ids are found at the keyword endpoint, which lists the keywords in decreasing number of events found. The common keywords used in all events originate from the general Finnish ontology (YSO), hence the format yso:p4354.

The most common event categories are listed in the two keyword sets helsinki:topics and helsinki:audiences, which list the YSO keywords that are present in most events to specify event main topic and audience.

Example:

event/?keyword=yso:p4354

See the result

event/?keyword_OR_set1=yso:p1235,yso:p1947&keyword_OR_set2=yso:p14004,yso:p11185

See the result

Keyword set search

Some services maintain curated keyword sets, which can also be used in search with query parameters keyword_set_AND and keyword_set_OR. As names of the keyword sets can repeat between the services, ids should be supplied. Say, we have one keyword set Music with id "myservice:1" that contains keywords rock and jazz, and another keyword set Workshops with keywords "workshop" and "seminar" and id "myservice:2". Then a request /event/?keyword_set_AND=myservice:1,myservice:2 would return the events matching the following expression: (rock OR jazz) AND (workshop OR seminar).

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

Specific ids

To find events that have specific id use parameter ids, separating values by commas if you wish to query for several event ids.

Example:

event/?ids=helsinki:1

See the result

Event status

Events in Linkedevents (indicated by the event_status field) may be either scheduled as planned (EventScheduled), rescheduled if their start time has changed after they were first published (EventRescheduled), cancelled if they were cancelled altogether after publication (EventCancelled), or postponed to the indefinite future if they could not be organized at the original time (EventPostponed). These statuses stem from schema.org.

You may filter events with only the desired status with the event_status filter.

Example:

event/?event_status=EventCancelled

See the result

It is also possible to use multiple event_status parameters in a single query. Statuses must be separated by a comma.

Example:

event/?event_status=EventCancelled,EventPostponed

Event type

Events in Linkedevents (indicated by the type_id field) may be event (General), course (Course) or volunteering (Volunteering). By default, only events with General type_id are returned.

You may filter events with only the desired type with the event_type filter, separating values by commas if you wish to query for several types.

Example:

event/?event_type=General,Course

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=shostakovich

See the result

Combined text

While the text search is looking for the events containg exact matches of the search string, combined_text filtering finds events with exact text match for event text fields but retrieves expected keywords on the basis of similarity. Filtering for keywords works similar ways as keyword free_text filtering.

Example:

event/?combined_text=lapppset

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 audience age boundaries.

To find events that are designed for specific age audiences use the query paramteres audience_min_age_lt, audience_min_age_gt, audience_max_age_lt, audience_max_age_gt.

audience_min_age_lt returns the events whose minimal age is lower than or equals the specified value, audience_min_age_gt returns the events whose minimal age is greater than or equals the specified value. max_age parameteres, naturally, work the same way only for the maximum age of the event audience. Note, that the events that are not designed for the specific audiences will be omitted.

audience_max_age and audience_min_age parameters without lt and gt modifiers are left for backward compatibility only and should not be employed.

Example:

event/?audience_min_age_gt=10

See the result

Select events suitable for certain age.

To find events that are suitable for certain age use the query paramter suitable_for that returns all the events that are suitable for the age or age range specified. Under the hood it excludes all the events that have max age limit below or min age limit above the age specified. Suitable events with just one age boundary specified are returned, events with no age limits specified are excluded. Query parameter can take either one or two arguments, the order of parameters when specifying the age range is not important.

Examples:

event/?suitable_for=12

See the result

event/?suitable_for=12,14

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.

Existing publisher organizations are found at the organization endpoint. City of Helsinki internal publishers have ids of the form ahjo:origin_id as they originate from the Helsinki Ahjo decisionmaking system, and have a rather complex hierarchy. External publishers may have their own namespaces, ids and hierarchies.

Also, it is possible to fetch events under a specific publisher organization hierarchy (say City of Helsinki) by using the parameter publisher_ancestor, which returns all events published by any suborganizations (at any level) of the given organization.

Example:

event/?publisher=ytj:0586977-6

See the result

event/?publisher_ancestor=ahjo:00001

See the result

Event data source

To find out events that originate from a specific source system, use the query parameter data_source. All event ids are of the form data_source:origin_id, so this allows you to return only events coming to Linkedevents from a specific data system. helsinki is the name of our own data source, i.e. events where Linkedevents API itself is the master data.

Example:

event/?data_source=helmet

See the result

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

Hide recurring children

You may use the query parameter hide_recurring_children to hide all child events for super events which are of type recurring.

Example:

event/?hide_recurring_children=true

See the result

Event with registration

To find out events with or without a registration, use the query parameterregistration.

Example:

event/?registration=true

See the result

Open enrolment

Two endpoints show the events that have connected registrations and have places either at the event itself enrolment_open or in the waiting lists enrolment_open_waitlist. Note that the latter query parameter when set to true returns also the events that have open spots at the event itself. Null values are regarded as unlimited number of spots at the event or in the waiting list.

For example:

event/?enrolment_open_waitlist=true

See the result

Enrolment open on a given date

It is possible to check if a given datetime is within events' enrolment start and end times. In other words, if any events are open on a given date and time. The given datetime is expected to be in the events' timezone.

enrolment_open_on parameter displays events where the given datetime is within the enrolment_start_time and enrolment_end_time of the events. If an event has a registration, the registration's enrolment start and end times will be preferred over the event's times.

For example:

event/?enrolment_open_on=2024-02-19T12:00:00

See the result

Attendee capacity

Filters for filtering by event maximum_attendee_capacity and minimum_attendee_capacity:

Filtering for maximum_attendee_capacity

It is possible to filter by maximum_attendee_capacity using gte (>) or lte (<) filters.

maximum_attendee_capacity_gte parameter displays events with maximum attendee capacity greater than or equal the applied parameter (integer value)

Example:

event/?maximum_attendee_capacity_gte=10

See the result

maximum_attendee_capacity_lte parameter displays events with maximum attendee capacity less than or equal the applied parameter (integer value)

Example:

event/?maximum_attendee_capacity_lte=10

See the result

Filtering for minimum_attendee_capacity

It is possible to filter by minimum_attendee_capacity using gte (>) or lte (<) filters.

minimum_attendee_capacity_gte parameter displays events with minimum attendee capacity greater than or equal the applied parameter (integer value)

Example:

event/?minimum_attendee_capacity_gte=10

See the result

minimum_attendee_capacity_lte parameter displays events with minimum attendee capacity less than or equal the applied parameter (integer value)

Example:

event/?minimum_attendee_capacity_lte=10

See the result

Remaining registration attendee or waiting list capacity

Filters for filtering by registration remaining_attendee_capacity and remaining_waiting_list_capacity:

Filtering for registration remaining_attendee_capacity

It is possible to filter by registration remaining_attendee_capacity using gte (>=) or isnull filters.

registration__remaining_attendee_capacity__gte parameter displays events where registration's remaining attendee capacity is greater than or equal the applied parameter (integer value)

Example:

event/?registration__remaining_attendee_capacity__gte=10

See the result

registration__remaining_attendee_capacity__isnull parameter displays events where registration's remaining attendee capacity is or is not NULL

The values True, true and 1 are all considered to be "true".

The values False, false and 0 are all considered to be "false".

Example:

event/?registration__remaining_attendee_capacity__isnull=true

See the result

Filtering for registration remaining_waiting_list_capacity

It is possible to filter by registration remaining_waiting_list_capacity using gte (>=) or isnull filters.

registration__remaining_waiting_list_capacity__gte parameter displays events where registration's remaining waiting list capacity is greater than or equal the applied parameter (integer value)

Example:

event/?registration__remaining_waiting_list_capacity__gte=10

See the result

registration__remaining_waiting_list_capacity__isnull parameter displays events where registration's remaining waiting list capacity is or is not NULL

The values True, true and 1 are all considered to be "true".

The values False, false and 0 are all considered to be "false".

Example:

event/?registration__remaining_waiting_list_capacity__isnull=true

See the result

Filtering for authenticated users

By default, only public events are shown in the event list. However, certain query parameters allow customizing the listing for authenticated users

Show all events

show_all parameter displays all events authenticated user can edit, including drafts, and public non-editable events

Example:

event/?show_all=true

See the result

Publication status

Events in Linkedevents (indicated by the publication_status field) may be either (draft) if the event is not published yet or (public) for published events.

You may filter events with only the desired publication status with the publication_status filter.

Example:

event/?publication_status=draft

See the result

Only editable events

admin_user parameter displays all events authenticated user can edit, including drafts, but no other public events

Example:

event/?admin_user=true

See the result

Only editable events for registration

registration_admin_user parameter displays all events whose registration the user can modify

Example:

event/?registration_admin_user=true

See the result

Events created by the user

created_by parameter only displays events by the authenticated user

Example:

event/?created_by=true

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, duration, enrolment_start_time, enrolment_end_time, registration__enrolment_start_time, registration__enrolment_end_time, enrolment_start and enrolment_end. Descending order is denoted by adding - in front of the parameter, default order is ascending.

For example:

event/?sort=-end_time

See the result

Enrolment start and enrolment end

The ordering filters enrolment_start and enrolment_end have two notable differences compared to the rest of the ordering filters related to enrolment start and enrolment end times:

First, if an event has a registration with an enrolment time defined, the registration's time will be preferred over the event's time.

Second, if neither the event's registration nor the event has enrolment times defined (enrolment_start_time and enrolment_end_time are both NULL), the event will be placed at the end of the results list regardless of whether ascending or descending order was used.

GET /linkedevents/v1/event/?format=api&publisher=ytj%253A0586977-6
HTTP 200 OK
Allow: GET, POST, PUT, PATCH, HEAD, OPTIONS
Content-Type: application/json ;utf-8
Vary: Accept

{
    "meta": {
        "count": 0,
        "next": null,
        "previous": null
    },
    "data": []
}