API Documentation

Fetching mbar event data for your app, mashup, publication or event aggregator

mbar offers a free, read only REST API for access to its programme data, including event, artist and club series information. No API key is required. Use of the API implies agreement to the license terms given below.

This document covers the current revision of the API, version 1.

Webcal, Rss and Atom feeds are also available. Please contact webmaster@mbar.fi with any questions. We'll also be delighted if you can let us know at that address of your use of the API.

License

The mbar programme data ("the database") described in this documentation is made available under the Open Database License:
http://opendatacommons.org/licenses/odbl/1.0/.

In short, you are free to use, adapt and redistribute the database, and create works based upon it, as long as you Attribute and Share-Alike. Please see http://opendatacommons.org/licenses/odbl/summary/ for explanations.

Any rights in individual contents of the database that are not produced by mbar, such as photographs and other images, are held by their respective authors unless otherwise noted. You are granted a limited license to use said contents only in conjunction with the database for the sole purpose of promoting or listing mbar's event programme. Any other use might be forbidden or require permission from the author of said content.

Any external content that might be linked from the database is entirely governed by the license terms set by the provider of said content.

API access

The API endpoint is located at http://mbar.fi/api/v1/

XML, JSON, JSONP and YAML formats are supported. Specify the format either with an Accept: -header or by appending format={xml,json,jsonp,yaml} to your query string. For JSONP, the name of the callback function can be specified with the callback parameter, the default name being 'callback'.

The API is built with django-tastypie 0.9.11. For more information on data access, see their documentation on fetching data.

Dates are formatted according to ISO 8601, times are in Helsinki local time. Text is UTF-8.

Fetching data

The following apply to all queries regardless of resource type.

Object listing

http://mbar.fi/api/v1/RESOURCETYPE/[?limit=x&offset=y]

Fetches a listing of resource objects of type RESOURCETYPE. You may optionally specify the maximum number of objects returned with the limit parameter (default 20, specify limit=0 to fetch all objects). Where there are more objects than limit, you can iterate through the results by specifying the offset of the first object to fetch.

The response will contain a list of resources under the objects key/tag, and a meta section with the total number of resources, the limit, the offset and the URLs of the eventual next and previous pages of results.

Single object

http://mbar.fi/api/v1/RESOURCETYPE/ID/

Returns the object of type RESOURCETYPE with the id ID.

Set of objects

http://mbar.fi/api/v1/RESOURCETYPE/set/ID1;ID2;ID3;.../

Returns all the objects of type RESOURCETYPE with the ids specified by the semicolon-separated list.

The response will contain a list of the requested resources under the objects key/tag.

Ordering

To order results according to a certain field, add order_by=FIELDNAME to your query string, or order_by=-FIELDNAME for reverse order. See the resource descriptions to find out which fields are sortable for each resource type.

Filtering

Append FIELDNAME=VALUE to the query string to filter results to those where the value of the specified field matches VALUE exactly. Additionally, you may also use the following formats:

  • FIELDNAME__iexact=VALUE — Field equals VALUE, case insensitive.
  • FIELDNAME__icontains=VALUE — Field contains VALUE, case insensitive.
  • FIELDNAME__istartswith=VALUE — Field starts with VALUE, case insensitive.
  • FIELDNAME__gt=VALUE — Field is greater than VALUE.
  • FIELDNAME__lt=VALUE — Field is less than VALUE.

 
This is only a subset, please see the Django documentation on field lookups for a complete list.

The resource descriptions below specify which fields are available for filtering for each resource type.

Resources

Event

Query Endpoint

http://mbar.fi/api/v1/event/

Ordering

Default ordering is by start time, descending (newest first).

  • name — the name of the event.
  • club — the id of the club series the event belongs to.
  • club__name — the name of the club series the event belongs to.
  • start_time — the event's start time.
  • time_modified — the timestamp of the last modification.

Filtering

The following fields can be filtered on. See above for modifiers that can be used with filters.

  • name — the name of the event.
  • club — the id of the club series the event belongs to.
  • club__name — the name of the club series the event belongs to.
  • start_time — the event's start time, in YYYY-MM-DD HH:MM[:ss[.uuuuuu]] format.
  • end_time — the event's end time, in YYYY-MM-DD HH:MM[:ss[.uuuuuu]] format.
  • time_modified — the timestamp of the last modification, in YYYY-MM-DD HH:MM[:ss[.uuuuuu]] format.

 
Additionally, a custom filter called datefilter is available for some common date and time filtering operations:

  • datefilter=ongoing — ongoing events.
  • datefilter=next — next events, including any ongoing ones.
  • datefilter=upcoming — upcoming events, excluding any ongoing ones.
  • datefilter=today — all events happening today (day changes at 4 in the morning).
  • datefilter=tomorrow — all events happening tomorrow (day changes at 4 in the morning).

Response data

Each event resource is represented by an object with the following fields:

  • resource_uri — the URI of this event resource.
  • resource_webpage_uri — the URI of this event webpage on mbar's site.
  • name — the event's name.
  • tagline — event tagline or subheading.
  • full_name — the event's name and tagline (subheading) concatenated.
  • oneliner — the event's name, tagline and performers on one line. If you can only show one line of information per event in your application, this is the recommended field to use.
  • lead — event description lead.
  • description — event description body.
  • start_time — event start time and date in ISO 8601 format, Helsinki local time.
  • end_time — event end time and date in ISO 8601 format, Helsinki local time.
  • picture_uri — event picture URI.
  • picture_caption — event picture caption.
  • club — the club series the event belongs to. An object with the following fields:
    • name — the club series' name.
    • resource_uri — the URI of the club series resource.
  • artists — a list of objects representing the artists performing at the event, each with the following fields:
    • act_name — the name under which the artist is performing.
    • resource_uri — the URI of the artist resource.
    • type — performance type (DJ, live, ...)
  • performers_string — a single string representing all of the artists performing at the event.
  • extrainfo_urls — a list of objects representing URLs pointing to extra info about the event, each with the following fields:
    • address — URL address.
    • description — URL description.
    • type — URL type (Facebook, homepage, ...)
  • fb_url — URL of the Facebook event page corresponding to this event.
  • price — Ticket price. Normally events at mbar are always free.
  • time_modified — the timestamp of the last modification.

Artist

Query Endpoint

http://mbar.fi/api/v1/artist/

Ordering

Default ordering is by name, ascending.

  • name — the name of the artist.
  • time_modified — the timestamp of the last modification.

Filtering

The following fields can be filtered on. See above for modifiers that can be used with filters.

  • name — the name of the artist.
  • extra_info — extra info such as artist affiliation or country of origin.
  • time_modified — the timestamp of the last modification, in YYYY-MM-DD HH:MM[:ss[.uuuuuu]] format.

Response data

Each artist resource is represented by an object with the following fields:

  • resource_uri — the URI of this artist resource.
  • resource_webpage_uri — the URI of this artist webpage on mbar's site.
  • name — the artist's name.
  • extra_info — extra info such as artist affiliation or country of origin.
  • full_name — name and extra_info combined.
  • lead — artist description lead.
  • description — artist description body.
  • picture_uri — artist picture URI.
  • picture_caption — artist picture caption.
  • clubs_hosted — a list of objects representing the club series this artist hosts, each with the following fields:
    • name — the club series' name.
    • resource_uri — the URI of the club series resource.
  • events — a list of objects representing the events featuring this artist, each with the following fields:
    • name — the name of the event.
    • tagline — event tagline or subheading.
    • full_name — the event's name and tagline (subheading) concatenated.
    • start_time — event start time and date in ISO 8601 format, Helsinki local time.
    • end_time — event end time and date in ISO 8601 format, Helsinki local time.
    • resource_uri — the URI of the event resource.
  • extrainfo_urls — a list of objects representing URLs pointing to extra info about the artist, each with the following fields:
    • address — URL address.
    • description — URL description.
    • type — URL type (Facebook, homepage, ...)
  • time_modified — the timestamp of the last modification.

Club Series

Query Endpoint

http://mbar.fi/api/v1/club/

Ordering

Default ordering is by name, ascending.

  • name — the name of the artist.
  • time_modified — the timestamp of the last modification.

Filtering

The following fields can be filtered on. See above for modifiers that can be used with filters.

  • name — the name of the club series.
  • time_modified — the timestamp of the last modification, in YYYY-MM-DD HH:MM[:ss[.uuuuuu]] format.

Response data

Each club series resource is represented by an object with the following fields:

  • resource_uri — the URI of this club series resource.
  • resource_webpage_uri — the URI of this club series webpage on mbar's site.
  • name — the club series' name.
  • lead — club series description lead.
  • description — club series description body.
  • picture_uri — club series picture URI.
  • picture_caption — club series picture caption.
  • hosts — a list of objects representing the artists hosts hosting this club series, each with the following fields:
    • full_name — the artist's name, with affiliation.
    • resource_uri — the URI of the artist resource.
  • events — a list of objects representing the events in this club series, each with the following fields:
    • name — the name of the event.
    • start_time — event start time and date in ISO 8601 format, Helsinki local time.
    • end_time — event end time and date in ISO 8601 format, Helsinki local time.
    • resource_uri — the URI of the event resource.
  • extrainfo_urls — a list of objects representing URLs pointing to extra info about the club series, each with the following fields:
    • address — URL address.
    • description — URL description.
    • type — URL type (Facebook, homepage, ...)
  • time_modified — the timestamp of the last modification.

Examples

Today at mbar

http://mbar.fi/api/v1/event/?datefilter=today

All club series listing, paginated

http://mbar.fi/api/v1/club/

An artist detail page

http://mbar.fi/api/v1/artist/28/

Next 5 events

http://mbar.fi/api/v1/event/?datefilter=next&limit=5

All events in a certain club series

http://mbar.fi/api/v1/event/?club__name__iexact=defence&limit=0

All events in August 2012

http://mbar.fi/api/v1/event/?start_time__gte=2012-08-01&start_time__lt=2012-09-01