Introduction

Welcome to the Teosto Open API. This documentation should help you familiarize yourself with the resources available. Read throught the Getting started section before you dive in.

The data includes all of the live events reported to Teosto by event organizers, performers and services that provide event information. This is the largest live music event database in Finland. We've also included location information on region, municipality and venue levels to help you get something more out of our data.

By using this API you agree to the Terms & Conditions of Teosto Open API.

If you come up with a great idea for using the Teosto Open API, we'd appreciate if you share it with us using the contact form!

Getting started

Authentication

Teosto Open API is completely open API. No authentication is required to request and get data. (This also means that we've limited what you can do to just GET-ing the data. If you find a mistake in the data, then contact us to let us know.)

Base URL

The Base URL is the root URL for all of the API. The Base URL is:

http://api.teosto.fi/2014

Year

Right now the API only includes data from 2014 but we will include datasets also for 2013 and 2015. Once we do, you can just change the year in the request string to get data from different years.

Request structure

The overall structure of the API request is very simple:

http://api.teosto.fi/{year}/{resource}?{parameters}
Year

Only 2014 is currently available. This value is required.

Resource

One of the various API resources described in this documentation. This value is optional but without this the response will not give you any actual information, just references to the real content.

Parameters

Each resource has different parameters that include for example identifiers, methods and pagination parameters. Parameters are usually optional and if you don't specify any parameter, you will get the default response. Some parameters on the other hand require another parameters. For example:

name / id -- Used to identify a specific resource.

method -- Method specifies what information to get from a specific resource. "Methods" can only be used with identifiers.

Methods and names are not case sensitive.

Responses

The response is always JSON. Responses include the data you were requesting, of course, and if you request a list of some sorts, the response will also include meta data.

If some piece of data is missing, for example a venue doesn't have a name but it still has all the other information, you will see the value <n/a> (not available). Only available data can be searched.

Response paging

If you request for a list, the response will include an object response_meta which has six meta information tags: page, limit, pages, previous, next and one that tells you the total number of objects in that list. These exists because we have limited the response to 100 objects per result set (page) as a default. We've also wanted to make it easy for you to move from one page to another, hence the previous and next tags, which will give you the url for the next or previous page requests. The previous and next URLs will change depenging on the limit and page you use in the request.

You can change the limit by using the limit method in your request string. The maximum value for limit is 1000. You can also skip pages by using the page method in your request string. For example:

/event?limit=20&page=3
{ "events" : [{ // event information }, ... ], "response_meta" : { "page" : 3, "limit" : 20, "pages" : 2818, "events" : 56347, "previous" : "/event/?limit=2&page=3", "next" : "/event/?limit=2&page=5", } }

This request will give you the events 41-60. The tag name used for total number in response_meta is always the same as the list objects name (highlighted on red).

Rate limit

Upon the new regulations, there is a limit on sending HTTP requests to the API. You will be able to make 5 requests per originating IP address per second in average.

Errors

Sometimes errors occur. Here's a list of error numbers (1-9) and also HTTP status codes to help you figure out what caused the unfortunate error. Successful responses have the HTTP status code 200.

  • 1 404 -- Invalid request Your request requires a valid format and a valid resource value.
  • 2 408 -- Invalid parameter(s) Your request contains invalid parameter(s).
  • 3 400 -- Request timeout The request failed because it took too long to respond.
  • 4 400 -- Invalid method. Your method is not valid.
  • 5 400 -- Missing method parameter(s) Your request is missing method parameter(s).
  • 6 404 -- Invalid method parameter(s) value Your request contains invalid method parameter(s) value.
  • 7 400 -- Invalid page limit value Your request contains invalid page limit value.
  • 8 400 -- Invalid page number value Your request contains invalid page number value.
  • 9 400 -- Invalid page limit and page number values Your request contains invalid page limit and page number values.
  • - 500 -- Undefined error The error is not defined, please contact with the support team.

Changelog

You can find the changelog here.

Resources

Below are all of the resources in this API.

All of the resource methods have examples for requests and responses, where you can see the format. We've snipped out the response_meta from the example responses but it will always be in the same format as described above.

Root

The Root resource provides information on all available resources within the API.

Example request:
Example response:
{ "region":{ "url":"/region", "count":21 }, "municipality":{ "url":"/municipality", "count":319 }, "place":{ "url":"/place", "count":6967 }, "venue":{ "url":"/venue", "count":8333 }, "event":{ "url":"/event", "count":52559 }, "show":{ "url":"/show", "count":58506 }, "performer":{ "url":"/performer", "count":12565 }, "work":{ "url":"/work", "count":62147 }, "author":{ "url":"/author", "count":24452 }, "role":{ "url":"/role", "count":5 }, "date":{ "url":"/date" }, "finland":{ "url":"/finland" } }

Finland

Finland resource is a collection of top lists from Finland.

Example request:
/finland?method=topWorks
Example response:
{ "topWorks":[ { "work":{ "id":"87a30e305ff492", "title":"PARATIISI", "url":"http://api.teosto.fi/2014/work?id=87a30e305ff492" }, "count":1243 }, { "work":{ "id":"86a10b3c53f99d", "title":"IKKUNAPRINSESSA", "url":"http://api.teosto.fi/2014/work?id=86a10b3c53f99d" }, "count":1074 }, ... ], "finland":{ "url":"http://api.teosto.fi/2014/finland" }, "response_meta":{ ... } }

Methods

  • /finland

    List of all the methods available for finland resource.

    Example request:
    /finland
    Example response:
    { "finland":{ "topWorks":{ "url":"http://api.teosto.fi/2014/finland?method=topWorks" } } }
  • /finland?method=topWorks

    List of top works played in Finland.

    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /finland?method=topWorks
    Example response:
    { "topWorks":[ { "work":{ "id":"87a30e305ff492", "title":"PARATIISI", "url":"http://api.teosto.fi/2014/work?id=87a30e305ff492" }, "count":1243 }, { "work":{ "id":"86a10b3c53f99d", "title":"IKKUNAPRINSESSA", "url":"http://api.teosto.fi/2014/work?id=86a10b3c53f99d" }, "count":1074 }, ... ], "finland":{ "url":"http://api.teosto.fi/2014/finland" }, "response_meta":{ } }

Region

A region resource is one region in Finland.

Example request:
/region?name=PIRKANMAA
Example response:
{ "region":{ "name":"PIRKANMAA", "municipalities":{ "url":"/region?name=PIRKANMAA&method=municipalities", "count":22 }, "places":{ "url":"/region?name=PIRKANMAA&method=places", "count":682 }, "venues":{ "url":"/region?name=PIRKANMAA&method=venues", "count":754 }, "events":{ "url":"/region?name=PIRKANMAA&method=events", "count":5300 }, "topWorks":{ "url":"/region?name=PIRKANMAA&method=topWorks" } } }

Methods

  • /region

    Get all the region resources.

    This is the default method for region resource.

    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /region
    Example response:
    { "regions":[ { "name":"AHVENANMAAN MAAKUNTA", "url":"/region?name=AHVENANMAAN%20MAAKUNTA" }, ... ], "response_meta":{ ... } }
  • /region?name={regionName}

    Basic info and URLs for more information about specific region.

    This is the default method for specific region.

    Reguired parameters
    • name Identifies one specific region.
    Example request:
    /region?name=PIRKANMAA
    Example response:
    { "region":{ "name":"PIRKANMAA", "municipalities":{ "url":"/region?name=PIRKANMAA&method=municipalities", "count":22 }, "places":{ "url":"/region?name=PIRKANMAA&method=places", "count":682 }, "venues":{ "url":"/region?name=PIRKANMAA&method=venues", "count":754 }, "events":{ "url":"/region?name=PIRKANMAA&method=events", "count":5300 }, "topWorks":{ "url":"/region?name=PIRKANMAA&method=topWorks" } } }
  • /region?name={regionName}&method=municipalities

    List of all the municipalities in one specific region.

    Reguired parameters
    • name Identifies one specific region.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /region?name=PIRKANMAA&method=municipalities
    Example response:
    { "municipalities":[ { "name":"AKAA", "url":"/municipality?name=AKAA" }, { "name":"URJALA", "url":"/municipality?name=URJALA" }, ... ], "region":{ "name":"PIRKANMAA", "url":"/region?name=PIRKANMAA" }, "response_meta":{ ... } }
  • /region?name={regionName}&method=places

    List of all the places in one specific region.

    Reguired parameters
    • name Identifies one specific region.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /region?name=PIRKANMAA&method=places
    Example response:
    { "places":[ { "id":"86a60d3f5d", "url":"/place?id=86a60d3f5d" }, ... ], "region":{ "name":"PIRKANMAA", "url":"/region?name=PIRKANMAA" }, "response_meta":{ ... } }
  • /region?name={regionName}&method=venues

    List of all the venues in one specific region.

    Reguired parameters
    • name Identifies one specific region.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /region?name=PIRKANMAA&method=venues
    Example response:
    { "venues":[ { "id":"86a60d3f5c", "name":"TOIJALAN YHTEISKOULU", "url":"/venue?id=86a60d3f5c" }, ... ], "region":{ "name":"PIRKANMAA", "url":"/region?name=PIRKANMAA" }, "response_meta":{ ... } }
  • /region?name={regionName}&method=events

    List of all the events in one specific region.

    Reguired parameters
    • name Identifies one specific region.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /region?name=PIRKANMAA&method=events
    Example response:
    { "events":[ { "id":"85a70b3b59", "name": "VALKOKANKAAN HELMIÄ", "startDate":"2014-05-10", "endDate":"2014-05-10", "url":"/event?id=85a70b3b59" }, ... ], "region":{ "name":"PIRKANMAA", "url":"/region?name=PIRKANMAA" }, "response_meta":{ ... } }
  • /region?name={regionName}&method=topWorks

    List of top works played in one specific region.

    Reguired parameters
    • name Identifies one specific region.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /region?name=PIRKANMAA&method=topWorks
    Example response:
    { "topWorks":[ { "work":{ "id":"85a00c315ff39d46", "title":"MENNYT MIES", "url":"/work?id=85a00c315ff39d46" }, "count":145 }, { "work":{ "id":"80a60f3c5ff397", "title":"HELPPOA HENGITTÄÄ", "url":"/work?id=80a60f3c5ff397" }, "count":140 }, ... ], "region":{ "name":"PIRKANMAA", "url":"/region?name=PIRKANMAA" }, "response_meta":{ ... } }

Municipality

A municipality resource is one municipality in Finland.

Example request:
/municipality?name=TAMPERE
Example response:
{ "municipality":{ "name":"TAMPERE", "region":{ "name":"PIRKANMAA", "url":"/region?name=PIRKANMAA" } "places":{ "url":"/municipality?name=TAMPERE&method=places", "count":297 }, "venues":{ "url":"/municipality?name=TAMPERE&method=venues", "count":344 }, "events":{ "url":"/municipality?name=TAMPERE&method=events", "count":3506 }, "topWorks":{ "url":"/municipality?name=TAMPERE&method=topWorks" } } }

Methods

  • /municipality

    Get all the municipality resources.

    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /municipality
    Example response:
    { "municipalities":[ { "name":"MAARIANHAMINA", "url":"/municipality?name=MAARIANHAMINA" }, ... ], "response_meta":{ ... } }
  • /municipality?name={municipalityName}

    Basic info and URLs for more information about specific municipality.

    Reguired parameters
    • name Identifies one specific municipality.
    Example request:
    /municipality?name=TAMPERE
    Example response:
    { "municipality":{ "name":"TAMPERE", "region":{ "name":"PIRKANMAA", "url":"/region?name=PIRKANMAA" }, "places":{ "url":"/municipality?name=TAMPERE&method=places", "count":297 }, "venues":{ "url":"/municipality?name=TAMPERE&method=venues", "count":344 }, "events":{ "url":"/municipality?name=TAMPERE&method=events", "count":3506 }, "topWorks":{ "url":"/municipality?name=TAMPERE&method=topWorks" } } }
  • /municipality?name={municipalityName}&method=places

    List of all the places in one specific municipality.

    Reguired parameters
    • name Identifies one specific municipality.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /municipality?name=TAMPERE&method=places
    Example response:
    { "places":[ { "id":"87a2013e5c", "url":"/place?id=87a2013e5c" }, { "id":"86a60e3c5d", "url":"/place?id=86a60e3c5d" }, ... ], "municipality":{ "name":"TAMPERE", "url":"/municipality?name=TAMPERE" }, "response_meta":{ ... } }
  • /municipality?name={municipalityName}&method=venues

    List of all the venues in one specific municipality.

    Reguired parameters
    • name Identifies one specific municipality.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /municipality?name=TAMPERE&method=venues
    Example response:
    { "venues":[ { "id":"86a60e3152", "name":"AIKALISÄ SPORT & MUSIC BAR", "url":"/venue?id=86a60e3152" }, { "id":"86a60f3853", "name":"AITOLAHDEN KIRKKO", "url":"/venue?id=86a60f3853" },{ "id":"86a60f3a59", "name":"AKTIA-LAULUTALO", "url":"/venue?id=86a60f3a59" }, ... ], "municipality":{ "name":"TAMPERE", "url":"/municipality?name=TAMPERE" }, "response_meta":{ ... } }
  • /municipality?name={municipalityName}&method=events

    List of all the events in one specific municipality.

    Reguired parameters
    • name Identifies one specific municipality.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /municipality?name=TAMPERE&method=events
    Example response:
    { "events":[ { "id":"87a50c", "name":"Tapahtuman nimi", "startDate":"2014-01-03", "endDate":"2014-01-03", "url":"/event?id=87a50c" }, ... ], "municipality":{ "name":"TAMPERE", "url":"/municipality?name=TAMPERE" }, "response_meta":{ ... } }
  • /municipality?name={municipalityName}&method=topWorks

    List of top works played in one specific municipality.

    Reguired parameters
    • name Identifies one specific municipality.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /municipality?name=TAMPERE&method=topWorks
    Example response:
    { "topWorks":[ { "work":{ "id":"80a60f3c5ff397", "title":"HELPPOA HENGITTÄÄ", "url":"/work?id=80a60f3c5ff397" }, "count":101 }, { "work":{ "id":"87aa0c3c58f193", "title":"OTON PÄIVÄ", "url":"/work?id=87aa0c3c58f193" }, "count":101 }, ... ], "municipality":{ "name":"TAMPERE", "url":"/municipality?name=TAMPERE" }, "response_meta":{ ... } }

Place

A place resource is one place in Finland. Most places have an address and their geocoordinates have been defined with that address. If an address hasn't been specified, the geocoordinates are the central coordinates of the municipality.

Places don't have names since they are basically just addresses so we've used IDs to identify them in the API.

Example request:
/place?id=86a4013f5e
Example response:
{ "place":{ "id":"86a4013f5e", "address":{ "streetAddress":"SILTAKATU 1", "zipCode":"80100", "postOffice":"JOENSUU" }, "geoCoordinates":{ "latitude":"62.599199", "longitude":"29.77099" }, "municipality":{ "name":"JOENSUU", "url":"/municipality?name=JOENSUU" }, "venues":{ "url":"/place?id=86a4013f5e&method=venues", "count":4 }, "topWorks":{ "url":"/place?id=86a4013f5e&method=topWorks" } } }

Methods

  • /place

    Get all the place resources.

    Optional parameters
    • page description
    • limit description
    Example request:
    /place
    Example response:
    { "places":[ { "id":"86a60d3f5e", "url":"/place?id=86a60d3f5e" }, { "id":"86a60d3f5d", "url":"/place?id=86a60d3f5d" }, ... ], "response_meta":{ ... } }
  • /place?id={placeID}

    Get the basic info and URLs for more information about specific place.

    Required parameters
    • id Identifies one specific place.
    Example request:
    /place?id=86a4013f5e
    Example response:
    { "place":{ "id":"86a4013f5e", "address":{ "streetAddress":"SILTAKATU 1", "zipCode":"80100", "postOffice":"JOENSUU" }, "geoCoordinates":{ "latitude":"62.599199", "longitude":"29.77099" }, "municipality":{ "name":"JOENSUU", "url":"/municipality?name=JOENSUU" }, "venues":{ "url":"/place?id=86a4013f5e&method=venues", "count":4 }, "topWorks":{ "url":"/place?id=86a4013f5e&method=topWorks" } } }
  • /place?id={placeID}&method=venues

    List of venues of one specific place.

    Required parameters
    • id Identifies one specific place.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /place?id=86a4013f5e&method=venues
    Example response:
    { "venues":[ { "id":"86a5093a5d", "name":"KERUBIN KEITTIÖ, JOENSUU", "url":"/venue?id=86a5093a5d" }, { "id":"86a5093a5c", "name":"KERUBIN KELLARI, JOENSUU", "url":"/venue?id=86a5093a5c" }, ... ], "place":{ "id":"86a4013f5e", "url":"/place?id=86a4013f5e" }, "response_meta":{ ... } }
  • /place?id={placeID}&method=topWorks

    List of top works played in one specific place.

    Required parameters
    • id Identifies one specific place.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /place?id=86a4013f5e&method=topWorks
    Example response:
    { "topWorks":[ { "work":{ "id":"8da4003e5cf093", "title":"AHMAT TULEVAT", "url":"/work?id=8da4003e5cf093" }, "count":3 }, { "work":{ "id":"8da50d3c5ff99d", "title":"AINA VAPAA TYYLI", "url":"/work?id=8da50d3c5ff99d" }, "count":3 }, ... ], "place":{ "id":"86a4013f5e", "url":"/place?id=86a4013f5e" }, "response_meta":{ ... } }

Venue

A venue resource is one venue in Finland. Venue's are unique but many venues can have the same address and place.

Example request:
/venue?id=86a5093a53
Example response:
{ "venue":{ "id":"86a5093a53", "name":"KERUBIN SALI", "place":{ "id":"86a4013f5e", "address":{ "streetAddress":"SILTAKATU 1", "zipCode":"80100", "postOffice":"JOENSUU" }, "geoCoordinates":{ "latitude":"62.599199", "longitude":"29.77099" }, "municipality":{ "name":"JOENSUU", "url":"/municipality?name=JOENSUU" }, "url":"/place?id=86a4013f5e" }, "events":{ "url":"/venue?id=86a5093a53&method=events", "count":6 }, "topWorks":{ "url":"/venue?id=86a5093a53&method=topWorks" } } }

Methods

  • /venue

    Get all the venue resources.

    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /venue
    Example response:
    { "venues":[ { "id":"86a60e3d52", "name":"10-KERHO", "url":"/venue?id=86a60e3d52" }, { "id":"86a60e3e5b", "name":"24BASEMENT", "url":"/venue?id=86a60e3e5b" }, ... ], "response_meta":{ ... } }
  • /venue?id={venueID}

    Get the basic info and URLs for more information about specific venue.

    Required parameters
    • id Identifies one specific venue.
    Example request:
    /venue?id=86a5093a53
    Example response:
    { "venue":{ "id":"86a5093a53", "name":"KERUBIN SALI", "place":{ "id":"86a4013f5e", "address":{ "streetAddress":"SILTAKATU 1", "zipCode":"80100", "postOffice":"JOENSUU" }, "geoCoordinates":{ "latitude":"62.599199", "longitude":"29.77099" }, "municipality":{ "name":"JOENSUU", "url":"/municipality?name=JOENSUU" }, "url":"/place?id=86a4013f5e" }, "events":{ "url":"/venue?id=86a5093a53&method=events", "count":6 }, "topWorks":{ "url":"/venue?id=86a5093a53&method=topWorks" } } }
  • /venue?id={venueID}&method=events

    List of events in one specific venue.

    Required parameters
    • id Identifies one specific venue.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /venue?id=86a5093a53&method=events
    Example response:
    { "events":[ { "id":"87ab0b3c58", "name":"8-APPRO", "startDate":"2014-04-24", "endDate":"2014-04-24", "url":"/event?id=87ab0b3c58" }, ... ], "venue":{ "id":"86a5093a53", "url":"/venue?id=86a5093a53" }, "response_meta":{ ... } }
  • /venue?id={venueID}&method=topWorks

    List of top works played in one specific venue.

    Required parameters
    • id Identifies one specific venue.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /venue?id=86a5093a53&method=topWorks
    Example response:
    { "topWorks":[ { "work":{ "id":"8da4003e5cf093", "title":"AHMAT TULEVAT", "url":"/work?id=8da4003e5cf093" }, "count":3 }, ... ], "venue":{ "id":"86a5093a53", "url":"/venue?id=86a5093a53" }, "response_meta":{ ... } }
  • /venue?name={venueName}

    You can search for a venue by name using this method. Use + as a word seperator.

    Required parameters
    • name String to seach for.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /venue?name=tavastia
    Example response:
    { "venues":[ { "id":"87a3013f58", "name":"TAVASTIA KLUBI", "url":"/venue?id=87a3013f58" } ], "response_meta":{ ... } }

Event

An event resource is one event. Usually events include only one show but there are of course bigger events like music festivals that include several shows.

Example request:
/event?id=86a309
Example response:
{ "event":{ "id":"86a309", "name":"PÄÄ KII, KATUJEN ÄÄNET", "startDate":"2014-01-03", "endDate":"2014-01-03", "venue":{ "id":"87a308385a", "name":"ROCK BAR MONTTU", "place":{ "id":"87a20b3e59", "url":"/place?id=87a20b3e59" }, "url":"/venue?id=87a308385a" }, "shows":{ "url":"/event?id=86a309&method=shows", "count":1 } } }

Methods

  • /event

    Get all the event resources.

    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /event
    Example response:
    { "events":[ { "id":"85a50c3e5a", "name":"KEVÄTLUKUKAUSI 2014/MATINEAT", "startDate":"2014-01-01", "endDate":"2014-01-01", "url":"/event?id=85a50c3e5a" }, ... ], "response_meta":{ ... } }
  • /event?id={eventID}

    Get the basic info and URLs for more information about specific event.

    Required parameters
    • id Identifies one specific event.
    Example request:
    /event?id=86a309
    Example response:
    { "event":{ "id":"86a309", "name":"PÄÄ KII, KATUJEN ÄÄNET", "startDate":"2014-01-03", "endDate":"2014-01-03", "venue":{ "id":"87a308385a", "name":"ROCK BAR MONTTU", "place":{ "id":"87a20b3e59", "url":"/place?id=87a20b3e59" }, "url":"/venue?id=87a308385a" }, "shows":{ "url":"/event?id=86a309&method=shows", "count":1 } } }
  • /event?id={eventID}&method=shows

    List of all the shows in one specific event.

    Required parameters
    • id Identifies one specific event.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /event?id=86a309&method=shows
    Example response:
    { "shows":[ { "id":"81a20c395bf390", "url":"/show?id=81a20c395bf390" }, { "id":"81a20c3958f594", "url":"/show?id=81a20c3958f594" } ], "event":{ "id":"86a309", "url":"/event?id=86a309" }, "response_meta":{ ... } }

Show

A show resource is one show in an event. Most of the events have only one show but bigger events like music festivals can have many shows. Shows don't have names so we've used IDs to identify them in the API.

Example request:
/show?id=85aa00
Example response:
{ "show":{ "id":"85aa00", "event":{ "id":"85aa00", "name":"MIKKO MANUEL", "startDate":"2014-01-11", "endDate":"2014-01-11", "venue":{ "id":"87a000385b", "name":"WILLIAM K TENNISPALATSI", "place":{ "id":"87a3013d5f", "url":"/place?id=87a3013d5f" }, "url":"/venue?id=87a000385b" }, "url":"/event?id=85aa00" }, "performer":{ "id":"85a508", "name":"MIKKO MANUEL", "url":"/performer?id=85a508" }, "works":{ "url":"/show?id=85aa00&method=works", "count":0 } } }

Methods

  • /show

    Get all the show resources.

    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /show
    Example response:
    { "shows":[ { "id":"85a2", "url":"/show?id=85a2", "performer":{ "performerID": "83", "performerName": "BULLET FOR MY VALENTINE", "url":"/performer?id=83" } }, { "id":"85a6", "url":"/show?id=85a6", "performer":{ "performerID": "85a0", "performerName": "JOHN MAYALL", "url":"/performer?id=85a0" } }, ... ], "response_meta":{ ... } }
  • /show?id={showID}

    Get the basic info and URLs for more information about specific show.

    Required parameters
    • id Identifies one specific show.
    Example request:
    /show?id=85aa00
    Example response:
    { "show":{ "id":"85aa00", "event":{ "id":"85aa00", "name":"MIKKO MANUEL", "startDate":"2014-01-11", "endDate":"2014-01-11", "venue":{ "id":"87a000385b", "name":"WILLIAM K TENNISPALATSI", "place":{ "id":"87a3013d5f", "url":"/place?id=87a3013d5f" }, "url":"/venue?id=87a000385b" }, "url":"/event?id=85aa00" }, "performer":{ "id":"85a508", "name":"MIKKO MANUEL", "url":"/performer?id=85a508" }, "works":{ "url":"/show?id=85aa00&method=works", "count":0 } } }
  • /show?id={showID}&method=works

    List of works played in one specific show.

    Required parameters
    • id Identifies one specific show.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /show?id=81a20c3958f496&method=works
    Example response:
    { "works":[ { "id":"85a20d315ff7", "title":"ALASKA", "url":"/work?id=85a20d315ff7" }, { "id":"8ca7083c5cf992", "title":"ASENTEELLA", "url":"/work?id=8ca7083c5cf992" }, ... ], "show":{ "id":"81a20c3958f496", "url":"/show?id=81a20c3958f496" }, "response_meta":{ ... } }

Performer

A performer resource is one unique unit of performers, that has been reported to Teosto as the performer of a show. Performer can consist of one ("Suvi Teräsniska") or several ("Suvi Teräsniska, Pave Maijanen, Virve Rosti") performers. Please use the performer data with caution as the data is not totally complete.

Example request:
/performer?id=85a3093a
Example response:
{ "performer":{ "id":"85a3093a", "name":"A. AALLON RYTMIORKESTERI", "shows":{ "url":"/performer?id=85a3093a&method=shows", "count":41 } } }

Methods

  • /performer

    Get all the performer resources.

    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /performer
    Example response:
    { "performers":[ { "id":"87a60f3e", "name":" DECADENT SOCIETY, BRAINL", "url":"/performer?id=87a60f3e" }, { "id":"8da00f", "name":" JUKKA, SAMI", "url":"/performer?id=8da00f" }, ... ], "response_meta":{ ... } }
  • /performer?id={performerID}

    Get the basic info and URLs for more information about specific performer unit.

    Required parameters
    • id Identifies one specific performer unit.
    Example request:
    /performer?id=85a3093a>
    Example response:
    { "performer":{ "id":"85a3093a", "name":"A. AALLON RYTMIORKESTERI", "shows":{ "url":"/performer?id=85a3093a&method=shows", "count":41 } } }
  • /performer?id={performerID}&method=shows

    List of shows with one specific performer unit.

    Required parameters
    • id Identifies one specific performer unit.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /performer?id=85a3093a&method=shows
    Example response:
    { "shows":[ { "id":"81a1093158f594", "url":"/show?id=81a1093158f594" }, { "id":"81a1093158f693", "url":"/show?id=81a1093158f693" } ], "performer":{ "id":"85a3093a", "name":"A. AALLON RYTMIORKESTERI", "url":"/performer?id=85a3093a" }, "response_meta":{ ... } }
  • /performer?name={performerName}

    You can search for a performer by name using this method. Use + as a word seperator.

    Required parameters
    • name String to seach for.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /performer?name=apulanta
    Example response:
    { "performers": [ { "id": "86ab0d", "name": "APULANTA", "url": "/performer?id=86ab0d" }, { "id": "85a20f315d", "name": "APULANTA, LEGION OF BOKOR", "url": "/performer?id=85a20f315d" } ], "response_meta": { ... } }

Work

A work resource is one work played in a show.

Example request:
/work?id=83a60b3a5ef593
Example response:
{ "work":{ "id":"83a60b3a5ef593", "title":"PARATIISI", "ISWC":"T-912.478.530-4", "authors":[ { "role":{ "titleAbbr":"AR", "title":"Arranger", "url":"/role?titleAbbr=AR" }, "author":{ "id":"86a30c3b5ef1", "firstname":"VEIKKO", "lastname":"AHVENAINEN", "url":"/author?id=86a30c3b5ef1" } }, ... ], "shows":{ "url":"/work?id=83a60b3a5ef593&method=shows", "count":57 }, "topMunicipalities":{ "url":"/work?id=83a60b3a5ef593&method=topMunicipalities" }, "topVenues":{ "url":"/work?id=83a60b3a5ef593&method=topVenues" } } }

Methods

  • /work

    List of all work resources.

    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /work
    Example response:
    { "works":[ { "id":"85a20a3a5df3954c", "title":"!LIAF CIPE", "url":"/work?id=85a20a3a5df3954c" }, { "id":"81a7003d5df697", "title":"'SWANDERFUL", "url":"/work?id=81a7003d5df697" }, ... ], "response_meta":{ ... } }
  • /work?id={workID}

    Get the basic info and URLs for more information about specific work.

    Reguired parameters
    • id Identifies one specific work.
    Example request:
    /work?id=83a60b3a5ef593
    Example response:
    { "work":{ "id":"83a60b3a5ef593", "title":"PARATIISI", "ISWC":"T-912.478.530-4", "authors":[ { "role":{ "titleAbbr":"AR", "title":"Arranger", "url":"/role?titleAbbr=AR" }, "author":{ "id":"86a30c3b5ef1", "firstname":"VEIKKO", "lastname":"AHVENAINEN", "url":"/author?id=86a30c3b5ef1" } }, ... ], "shows":{ "url":"/work?id=83a60b3a5ef593&method=shows", "count":57 }, "topMunicipalities":{ "url":"/work?id=83a60b3a5ef593&method=topMunicipalities" }, "topVenues":{ "url":"/work?id=83a60b3a5ef593&method=topVenues" } } }
  • /work?id={workID}&method=shows

    List of shows where one specific work was performed.

    Reguired parameters
    • id Identifies one specific work.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /work?id=83a60b3a5ef593&method=shows
    Example response:
    { "shows":[ { "id":"81a20c3958f496", "event":{ "id":"8da10b", "name":"ANNELI MATTILA,RATTO", "startDate":"2014-01-11", "endDate":"2014-01-11", "url":"/event?id=8da10b" }, "url":"/show?id=81a20c3958f496" }, ... ], "work":{ "id":"83a60b3a5ef593", "title":"PARATIISI", "url":"/work?id=83a60b3a5ef593" }, "response_meta":{ ... } }
  • /work?id={workID}&method=topMunicipalities

    List of top municipalities where one specific work has been performed the most.

    Reguired parameters
    • id Identifies one specific work.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /work?id=83a60b3a5ef593&method=topMunicipalities
    Example response:
    { "topMunicipalities":[ { "municipality":{ "name":"LAHTI", "url":"/municipality?name=LAHTI" }, "count":10 }, { "municipality":{ "name":"LAIVAT", "url":"/municipality?name=LAIVAT" }, "count":10 }, ... ], "work":{ "id":"83a60b3a5ef593", "title":"PARATIISI", "url":"/work?id=83a60b3a5ef593" }, "response_meta":{ ... } }
  • /work?id={workID}&method=topVenues

    List of top venues where one specific work has been performed the most.

    Reguired parameters
    • id Identifies one specific work.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /work?id=83a60b3a5ef593&method=topVenues
    Example response:
    { "topVenues":[ { "venue":{ "id":"86aa0d3959", "name":"M/S VIKING GRACE, VIKING LINE", "url":"/venue?id=86aa0d3959" }, "count":10 },{ "venue":{ "id":"87a3013b5d", "name":"TANSSIRAVINTOLA PESÄKALLIO", "url":"/venue?id=87a3013b5d" }, "count":10 }, ... ], "work":{ "id":"83a60b3a5ef593", "title":"PARATIISI", "url":"/work?id=83a60b3a5ef593" }, "response_meta":{ ... } }
  • /work?title={workName}

    You can search for a work by title using this method. Use + as a word seperator.

    Reguired parameters
    • title String to search for.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /work?title=joulu
    Example response:
    { "works":[ { "id":"85a70f3f5df6974e", "title":"(JOULUUN ON KÄTKETTY) SALAISUUS", "url":"/work?id=85a70f3f5df6974e" }, { "id":"85a70f3f5df6974e", "title":"AINAISTEN LASTEN JOULU", "url":"/work?id=85a70f3f5df6974e" }, ... ], "response_meta":{ ... } }

Author

An author resource is one person who has participated in producing a work.

Example request:
/author?id=85a2083e59f892
Example response:
{ "author":{ "id":"85a2083e59f892", "firstname":"ELVIS", "lastname":"PRESLEY", "works":{ "url":"/author?id=85a2083e59f892&method=works", "count":4 }, "topWorks":{ "url":"/author?id=85a2083e59f892&method=topWorks" }, "topVenues":{ "url":"/author?id=85a2083e59f892&method=topVenues" } } }

Methods

  • /author

    List of all author resources.

    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /author
    Example response:
    { "authors":[ { "id":"86a40c3c5ef594", "firstname":"", "lastname":"A GHOUL WRITER", "url":"/author?id=86a40c3c5ef594" }, { "id":"8ca70d3b59f1", "firstname":"", "lastname":"AAPELI", "url":"/author?id=8ca70d3b59f1" }, ... ], "response_meta":{ ... } }
  • /author?id={authorID}

    Get the basic info and URLs for more information about one specific author.

    Reguired parameters
    • id Identifies one specific author.
    Example request:
    /author?id=85a2083e59f892
    Example response:
    { "author":{ "id":"85a2083e59f892", "firstname":"ELVIS", "lastname":"PRESLEY", "works":{ "url":"/author?id=85a2083e59f892&method=works", "count":4 }, "topWorks":{ "url":"/author?id=85a2083e59f892&method=topWorks" }, "topVenues":{ "url":"/author?id=85a2083e59f892&method=topVenues" } } }
  • /author?id={authorID}&method=works

    List of all the works from one specific author.

    Reguired parameters
    • id Identifies one specific author.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /author?id=85a2083e59f892&method=works
    Example response:
    { "works":[ { "id":"80a1093b5ef4", "title":"ALL SHOOK UP", "url":"/work?id=80a1093b5ef4" }, { "id":"80a70e3b5cf4", "title":"DON'T BE CRUEL", "url":"/work?id=80a70e3b5cf4" }, ... ], "author":{ "id":"85a2083e59f892", "firstname":"ELVIS", "lastname":"PRESLEY", "url":"/author?id=85a2083e59f892" }, "response_meta":{ ... } }
  • /author?id={authorID}&method=topWorks

    List of top works from one specific author.

    Reguired parameters
    • id Identifies one specific author.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /author?id=85a2083e59f892&method=topWorks
    Example response:
    { "topWorks":[ { "work":{ "id":"80a1093b5ef4", "title":"ALL SHOOK UP", "url":"/work?id=80a1093b5ef4" }, "count":164 }, ... ], "author":{ "id":"85a2083e59f892", "firstname":"ELVIS", "lastname":"PRESLEY", "url":"/author?id=85a2083e59f892" }, "response_meta":{ ... } }
  • /author?id={authorID}&method=topVenues

    List of top venues where one specific author has been played.

    Reguired parameters
    • id Identifies one specific author.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /author?id=85a2083e59f892&method=topVenues
    Example response:
    { "topVenues":[ { "venue":{ "id":"86aa0c315d", "name":"M/S FINLANDIA, ECKERÖ LINE", "url":"/venue?id=86aa0c315d" }, "count":19 }, { "venue":{ "id":"86a5003f5b", "name":"KYLPYLÄHOTELLI LEVITUNTURI", "url":"/venue?id=86a5003f5b" }, "count":15 }, ... ], "author":{ "id":"85a2083e59f892", "firstname":"ELVIS", "lastname":"PRESLEY", "url":"/author?id=85a2083e59f892" }, "response_meta":{ ... } }

Role

A role resource is one of the roles authors have when creating a work. These include for example authors, composers and arrangers.

Example request:
/role?titleAbbr=C
Example response:
{ "role":{ "titleAbbr":"C", "title":"Composer", "description":"Composer", "topAuthors":{ "url":"/role?titleAbbr=C&method=topAuthors" } } }

Methods

  • /role

    Get a list of all the roles.

    Example request:
    /role
    Example response:
    { "roles":[ { "titleAbbr":"A", "title":"Author", "url":"/role?titleAbbr=A" }, ... ], "response_meta":{ ... } }
  • /role?titleAbbr={titleAbbr}

    Get info and URLs for more information about one specific role.

    Reguired parameters
    • titleAbbr Abbreviation of the role title. Specifies what role to request.
    Example request:
    /role?titleAbbr=C
    Example response:
    { "role":{ "titleAbbr":"C", "title":"Composer", "description":"Composer", "topAuthors":{ "url":"/role?titleAbbr=C&method=topAuthors" } } }
  • /role?titleAbbr={titleAbbr}&method=topAuthors

    Top most played authors in this role.

    Reguired parameters
    • titleAbbr Abbreviation of the role title. Specifies what role to request.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /role?titleAbbr=C&method=topAuthors
    Example response:
    { "topAuthors":[ { "author":{ "id":"86a30b3f5ff7", "firstname":"JUHA HARRI", "lastname":"VAINIO", "url":"/author?id=86a30b3f5ff7" }, "count":13998 }, ... ], "role":{ "titleAbbr":"C", "title":"Composer", "url":"/role?titleAbbr=C" }, "response_meta":{ ... } }

Date

Date resource gives you information about the events and what date they were happening. There are a few methods here to help you find what events there were in whichever day.

Note that if the event has a different start and end date, the API uses the start date. For example the response for a Date request will be events that start on the specific date.

Example request:
/date?date=2014-06-28
Example response:
{ "date":{ "date":"2014-06-28", "eventCount":377, "startDate":{ "url":"/date?startDate=2014-06-28", "count":377 }, "month":{ "url":"/date?month=6", "count":4204 }, "weekday":{ "url":"/date?weekday=7", "count":17330 } } }

Methods

  • /date

    List of all dates that have an event. Note that if the event has a different start and end date, the API uses the start date. For example the request result for a Date request will be events that start on the specific date.

    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /date
    Example response:
    { "dates":[ { "date":"2014-01-01", "eventCount":91, "url":"/date?date=2014-01-01" }, { "date":"2014-01-02", "eventCount":37, "url":"/date?date=2014-01-02" }, ... ], "response_meta":{ ... } }
  • /date?date={yyyy-mm-dd}

    Basic info and URLs for more information about the specific date.

    Reguired parameters
    • date Specifies what date to request.
    Example request:
    /date?date=2014-06-28
    Example response:
    { "date":{ "date":"2014-06-28", "eventCount":377, "startDate":{ "url":"/date?startDate=2014-06-28", "count":377 }, "month":{ "url":"/date?month=6", "count":4204 }, "weekday":{ "url":"/date?weekday=7", "count":17330 } } }
  • /date?startDate={yyyy-mm-dd}

    List of events that start on this date.

    Reguired parameters
    • startDate Specifies what date to request.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /date?startDate=2014-06-28
    Example response:
    { "events":[ { "id":"81a00b3052", "name":"DANS", "startDate":"2014-06-28", "endDate":"2014-06-28", "url":"/event?id=81a00b3052" }, { "id":"82a10b", "name":"TANSSIT", "startDate":"2014-06-28", "endDate":"2014-06-28", "url":"/event?id=82a10b" }, ... ], "response_meta":{ ... } }
  • /date?month={monthNumber}

    List of events in this month.

    Reguired parameters
    • month Specifies what month to request.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /date?month=6
    Example response:
    { "events":[ { "id":"86a50b", "name":"BANGERZ TOUR", "startDate":"2014-06-01", "endDate":"2014-06-10", "url":"/event?id=86a50b" }, { "id":"85a408395a", "name":"LOUHELA JAM 2014", "startDate":"2014-06-01", "endDate":"2014-06-01", "url":"/event?id=85a408395a" }, ... ], "response_meta":{ ... } }
  • /date?weekday={weekdayNumber}

    List of events on one specific weekday. The weekdays are queried by number so 1 equals Monday, 2 Tuesday and so on.

    Reguired parameters
    • weekday Specifies what weekday to request.
    Optional parameters
    • page What page of the list to request.
    • limit How many objects to show on one page.
    Example request:
    /date?weekday=6
    Example response:
    { "events":[ { "id":"87a40d", "name":"VIIHDEPIANISTI", "startDate":"2014-01-03", "endDate":"2014-01-03", "url":"/event?id=87a40d" }, { "id":"87a0013d", "name":"DREAMS 9 ?", "startDate":"2014-01-03", "endDate":"2014-01-03", "url":"/event?id=87a0013d" }, ... ], "response_meta":{ ... } }