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/2015

Year

The API includes data from 2014 and 2015. Change the year in the request string to get data from different years.

NOTE: Right now the IDs don't match between years. This means for example that a Venue will have different IDs depending on the year you request. We are currently working on matching the IDs, please check back soon.

Request structure

The overall structure of the API request is very simple:

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

Only 2014 and 2015 are 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.

Legacy

Since we added 2015 data, some songs, authors, venues, and performers might have two different IDs depending on what year you request. We've combined most of the resources to have the same ID every year so if you want to use the new combined IDs, you should use the parameter legacy to query them.

/venue?legacy=0

The default is legacy=1, which gives you the old IDs. Using this parameter won't affect 2015 data which only uses the new IDs.

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=4
{ "events" : [{ // event information }, ... ], "response_meta" : { "page" : 4, "limit" : 20, "pages" : 2581, "events" : 51610, "previous" : "/event/?limit=20&page=3", "next" : "/event/?limit=20&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":7277 }, "venue":{ "url":"/venue", "count":8040 }, "event":{ "url":"/event", "count":51610 }, "show":{ "url":"/show", "count":60145 }, "performer":{ "url":"/performer", "count":11960 }, "work":{ "url":"/work", "count":71784 }, "author":{ "url":"/author", "count":33991 }, "role":{ "url":"/role", "count":6 }, "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":"85a4003053", "title":"PARATIISI", "url":"http://api.teosto.fi/2015/work?id=85a4003053" }, "count":1526 }, { "work":{ "id":"85a4013b5e", "title":"HILJAISET SILLAT", "url":"http://api.teosto.fi/2015/work?id=85a4013b5e" }, "count":1155 }, ... ], "finland":{ "url":"http://api.teosto.fi/2015/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/2015/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":"85a4003053", "title":"PARATIISI", "url":"http://api.teosto.fi/2015/work?id=85a4003053" }, "count":1526 }, { "work":{ "id":"85a4013b5e", "title":"HILJAISET SILLAT", "url":"http://api.teosto.fi/2015/work?id=85a4013b5e" }, "count":1155 }, ... ], "finland":{ "url":"http://api.teosto.fi/2015/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":774 }, "venues":{ "url":"/region?name=PIRKANMAA&method=venues", "count":859 }, "events":{ "url":"/region?name=PIRKANMAA&method=events", "count":5380 }, "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":774 }, "venues":{ "url":"/region?name=PIRKANMAA&method=venues", "count":859 }, "events":{ "url":"/region?name=PIRKANMAA&method=events", "count":5380 }, "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":"86", "url":"/place?id=86" }, ... ], "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": "80a20f3f", "name": "MÄNTYMÄEN HOIVAKOTI", "url":"/venue?id=80a20f3f" }, ... ], "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":"85a6083852f695", "name": "HB DUO MONTTU", "startDate": "2015-01-01", "endDate": "2015-01-01", "url":"/event?id=85a6083852f695" }, ... ], "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":"85a70e3e5a", "title":"TAMMERKOSKI", "url":"/work?id=85a70e3e5a" }, "count":134 }, { "work":{ "id":"80a30e3d5d", "title":"SULOINEN MYRKYNKEITTÄJÄ", "url":"/work?id=80a30e3d5d" }, "count":111 }, ... ], "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":335 }, "venues":{ "url":"/municipality?name=TAMPERE&method=venues", "count":385 }, "events":{ "url":"/municipality?name=TAMPERE&method=events", "count":3583 }, "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":"AKAA", "url":"/municipality?name=AKAA" }, ... ], "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":335 }, "venues":{ "url":"/municipality?name=TAMPERE&method=venues", "count":385 }, "events":{ "url":"/municipality?name=TAMPERE&method=events", "count":3583 }, "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":"82a20d3c", "url":"/place?id=82a20d3c" }, { "id":"82a3093c", "url":"/place?id=82a3093c" }, ... ], "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":"81a1", "name":"AIKALISÄ SPORT & MUSIC BAR", "url":"/venue?id=81a1" }, { "id":"82a6", "name":"AITOLAHDEN KIRKKO", "url":"/venue?id=82a6" }, { "id":"83a7", "name":"AKTIIVI PÄIVÄTOIMINTA", "url":"/venue?id=83a7" }, ... ], "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":"85a1003f58f29d", "name":"Tapahtuman nimi", "startDate":"2015-01-30", "endDate":"2015-01-30", "url":"/event?id=85a1003f58f29d" }, ... ], "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":"87ab0f3959", "title":"LEMMENNOSTOHUMPPA", "url":"/work?id=87ab0f3959" }, "count":69 }, { "work":{ "id":"87ab0e3159", "title":"JOS MUN TUTTUNI TULISI", "url":"/work?id=87ab0e3159" }, "count":65 }, ... ], "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=87aa0a30
Example response:
{ "place":{ "id":"87aa0a30", "address":{ "streetAddress":"SILTAKATU 1 ILOSAARI", "zipCode":"80100", "postOffice":"JOENSUU" }, "geoCoordinates":{ "latitude":"62.599404", "longitude":"29.77166" }, "municipality":{ "name":"JOENSUU", "url":"/municipality?name=JOENSUU" }, "venues":{ "url":"/place?id=87aa0a30&method=venues", "count":1 }, "topWorks":{ "url":"/place?id=87aa0a30&method=topWorks" } } }

Methods

  • /place

    Get all the place resources.

    Optional parameters
    • page description
    • limit description
    Example request:
    /place
    Example response:
    { "places":[ { "id":"86", "url":"/place?id=86" }, { "id":"80a301", "url":"/place?id=80a301" }, ... ], "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=87aa0a30
    Example response:
    { "place":{ "id":"87aa0a30", "address":{ "streetAddress":"SILTAKATU 1 ILOSAARI", "zipCode":"80100", "postOffice":"JOENSUU" }, "geoCoordinates":{ "latitude":"62.599404", "longitude":"29.77166" }, "municipality":{ "name":"JOENSUU", "url":"/municipality?name=JOENSUU" }, "venues":{ "url":"/place?id=87aa0a30&method=venues", "count":1 }, "topWorks":{ "url":"/place?id=87aa0a30&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=87aa0a30&method=venues
    Example response:
    { "venues":[ { "id":"86a60b30", "name":"KERUBI", "url":"/venue?id=86a60b30" } ], "place":{ "id":"87aa0a30", "url":"/place?id=87aa0a30" }, "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=87aa0a30&method=topWorks
    Example response:
    { "topWorks":[ { "work":{ "id":"80a30d3058", "title":"AINA MINÄ JÄÄN", "url":"/work?id=80a30d3058" }, "count":3 }, { "work":{ "id":"80a70b3e59", "title":"ELÄMÄ LUPAA MULLE", "url":"/work?id=80a70b3e59" }, "count":3 }, ... ], "place":{ "id":"87aa0a30", "url":"/place?id=87aa0a30" }, "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=86a60b30
Example response:
{ "venue":{ "id":"86a60b30", "name":"KERUBI", "place":{ "id":"87aa0a30", "address":{ "streetAddress":"SILTAKATU 1 ILOSAARI", "zipCode":"80100", "postOffice":"JOENSUU" }, "geoCoordinates":{ "latitude":"62.599404", "longitude":"29.77166" }, "municipality":{ "name":"JOENSUU", "url":"/municipality?name=JOENSUU" }, "url":"/place?id=87aa0a30" }, "events":{ "url":"/venue?id=86a60b30&method=events" }, "topWorks":{ "url":"/venue?id=86a60b30&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":"8c", "name":" MÄNNISTÖN TANSSILAVA", "url":"/venue?id=8c" }, { "id":"85a2", "name":" RÄIKÄNPUISTO", "url":"/venue?id=85a2" }, ... ], "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=86a60b30
    Example response:
    { "venue":{ "id":"86a60b30", "name":"KERUBI", "place":{ "id":"87aa0a30", "address":{ "streetAddress":"SILTAKATU 1 ILOSAARI", "zipCode":"80100", "postOffice":"JOENSUU" }, "geoCoordinates":{ "latitude":"62.599404", "longitude":"29.77166" }, "municipality":{ "name":"JOENSUU", "url":"/municipality?name=JOENSUU" }, "url":"/place?id=87aa0a30" }, "events":{ "url":"/venue?id=86a60b30&method=events" }, "topWorks":{ "url":"/venue?id=86a60b30&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=86a60b30&method=events
    Example response:
    { "events":[ { "id": "85a60a395ef893", "name": "22-PISTEPIRKKO, CROOKED COIL", "startDate": "2015-04-03", "endDate": "2015-04-03", "url": "/event?id=85a60a395ef893" }, ... ], "venue":{ "id":"86a60b30", "url":"/venue?id=86a60b30" }, "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=86a60b30&method=topWorks
    Example response:
    { "topWorks":[ { "work":{ "id":"80a30d3058", "title":"AINA MINÄ JÄÄN", "url":"/work?id=80a30d3058" }, "count":3 }, ... ], "venue":{ "id":"86a60b30", "url":"/venue?id=86a60b30" }, "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":"82ab0f3a", "name":"TAVASTIA KLUBI", "url":"/venue?id=82ab0f3a" } ], "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=85a60c3e5cf796
Example response:
{ "event":{ "id":"85a60c3e5cf796", "name":"SVART FESTIVAL", "startDate": "2015-11-27", "endDate": "2015-11-27", "venue": { "id": "80a00a30", "name": "NOSTURI", "place": { "id": "80a40d", "url": "/place?id=80a40d" }, "url": "/venue?id=80a00a30" }, "shows":{ "url":"/event?id=85a60c3e5cf796&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":"85a10f3f5af59c", "name":"PALJAKKA", "startDate":"2015-01-01", "endDate":"2015-01-01", "url":"/event?id=85a10f3f5af59c" }, ... ], "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=85a60c3e5cf796
    Example response:
    { "event":{ "id":"85a60c3e5cf796", "name":"SVART FESTIVAL", "startDate": "2015-11-27", "endDate": "2015-11-27", "venue": { "id": "80a00a30", "name": "NOSTURI", "place": { "id": "80a40d", "url": "/place?id=80a40d" }, "url": "/venue?id=80a00a30" }, "shows":{ "url":"/event?id=85a60c3e5cf796&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=85a60c3e5cf796&method=shows
    Example response:
    { "shows":[ { "id":"80a4093b5a", "url":"/show?id=80a4093b5a" }, { "id":"80a4093b59", "url":"/show?id=80a4093b59" }, ... ], "event":{ "id":"85a60c3e5cf796", "url":"/event?id=85a60c3e5cf796" }, "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. We've used IDs to identify shows in the API. Shows from 2015 also include the name of the show.

Example request:
/show?id=86
Example response:
{ "show":{ "id":"86", "event":{ "id":"85a10c3f53f793", "name":"THE PRISMATIC WORLD TOUR", "startDate": "2015-03-18", "endDate": "2015-03-18", "venue":{ "id":"85a20839", "name":"HARTWALL AREENA", "place":{ "id":"85a40d", "url":"/place?id=85a40d" }, "url":"/venue?id=85a20839" }, "url":"/event?id=85a10c3f53f793" }, "performer":{ "id":"81a20e3e", "name":"KATY PERRY, CHARLI XCX", "url":"/performer?id=81a20e3e" }, "works":{ "url":"/show?id=86&method=works", "count":19 } } }

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":"85", "url":"/show?id=85", "performer":{ "performerID": "8cab093c", "performerName": "RYTMIROTAT", "url":"/performer?id=8cab093c" } }, { "id":"86", "url":"/show?id=86", "performer":{ "performerID": "81a20e3e", "performerName": "KATY PERRY, CHARLI XCX", "url":"/performer?id=81a20e3e" } }, ... ], "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=86
    Example response:
    { "show":{ "id":"86", "event":{ "id":"85a10c3f53f793", "name":"THE PRISMATIC WORLD TOUR", "startDate": "2015-03-18", "endDate": "2015-03-18", "venue":{ "id":"85a20839", "name":"HARTWALL AREENA", "place":{ "id":"85a40d", "url":"/place?id=85a40d" }, "url":"/venue?id=85a20839" }, "url":"/event?id=85a10c3f53f793" }, "performer":{ "id":"81a20e3e", "name":"KATY PERRY, CHARLI XCX", "url":"/performer?id=81a20e3e" }, "works":{ "url":"/show?id=86&method=works", "count":19 } } }
  • /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=86&method=works
    Example response:
    { "works":[ { "id": "85a2083159", "title": "HOT N COLD", "url": "/work?id=85a2083159" }, { "id": "85a2083158", "title": "I KISSED A GIRL", "url": "/work?id=85a2083158" }, ... ], "show":{ "id":"86", "url":"/show?id=86" }, "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=87aa0c3d
Example response:
{ "performer":{ "id":"87aa0c3d", "name":"JARI SILLANPÄÄ", "shows":{ "url":"/performer?id=87aa0c3d&method=shows", "count":91 } } }

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":"80a5", "name":"\"SAVONLINNA-KVARTETTI; RIITTA-LEENA LEMPINEN-VESA, SELLO; HA\t\r\n58886\t9253\tSAVONLINNA-KVARTETTI SAVONLINNAN ORKESTERI SAVONLINNAN MUSII\t\r\n58887\t46\t\"SAVONLINNA-KVARTETTI AVUSTAJINEEN; SAVONLINNA-KUORO; ", "url":"/performer?id=80a5" }, { "id":"80aa", "name":"\"SAVONLINNAN ORKESTERI; SOLISTEINA SAVONLINNAN MUSIIKKIOPIST\t\r\n44692\t7776\tPASI PIHLAJA, KÄYRÄTORVI MARGARITA GLOUKHOVA, PIANO\t\r\n44693\t9694\tSOLISTEINA SAVONLINNAN MUSIIKKIOPISTON OPPILAITA\t\r\n44694\t6365", "url":"/performer?id=80aa" }, ... ], "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=87aa0c3d>
    Example response:
    { "performer":{ "id":"87aa0c3d", "name":"JARI SILLANPÄÄ", "shows":{ "url":"/performer?id=87aa0c3d&method=shows", "count":91 } } }
  • /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=87aa0c3d&method=shows
    Example response:
    { "shows":[ { "id":"85a608", "url":"/show?id=85a608" }, { "id":"8ca20d", "url":"/show?id=8ca20d" } ], "performer":{ "id":"87aa0c3d", "name":"JARI SILLANPÄÄ", "url":"/performer?id=87aa0c3d" }, "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": "82a108", "name": "APULANTA", "url": "/performer?id=82a108" } ], "response_meta": { ... } }

Work

A work resource is one work played in a show. Currently ISWC numbers are not included in the 2015 data.

Example request:
/work?id=85aa0c385a
Example response:
{ "work":{ "id":"85aa0c385a", "title":"PARATIISI", "ISWC":"", "authors":[ { "role":{ "titleAbbr":"AR", "title":"Arranger", "url":"/role?titleAbbr=AR" }, "author":{ "id":"86a2093059f09d", "firstname":"VEIKKO", "lastname":"AHVENAINEN", "url":"/author?id=86a2093059f09d" } }, ... ], "shows":{ "url":"/work?id=85aa0c385a&method=shows", "count":31 }, "topMunicipalities":{ "url":"/work?id=85aa0c385a&method=topMunicipalities" }, "topVenues":{ "url":"/work?id=85aa0c385a&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":"85a60c385e", "title":"!LIAF CIPE", "url":"/work?id=85a60c385e" }, { "id":"86a00c3859", "title":"\"CAFE 512\"", "url":"/work?id=86a00c3859" }, ... ], "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=85aa0c385a
    Example response:
    { "work":{ "id":"85aa0c385a", "title":"PARATIISI", "ISWC":"", "authors":[ { "role":{ "titleAbbr":"AR", "title":"Arranger", "url":"/role?titleAbbr=AR" }, "author":{ "id":"86a2093059f09d", "firstname":"VEIKKO", "lastname":"AHVENAINEN", "url":"/author?id=86a2093059f09d" } }, ... ], "shows":{ "url":"/work?id=85aa0c385a&method=shows", "count":31 }, "topMunicipalities":{ "url":"/work?id=85aa0c385a&method=topMunicipalities" }, "topVenues":{ "url":"/work?id=85aa0c385a&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=85aa0c385a&method=shows
    Example response:
    { "shows":[ { "id":"87a4003e", "event":{ "id":"85a1013f58f794", "name":"RATTOBAND", "startDate":"2015-01-10", "endDate":"2015-01-10", "url":"/event?id=85a1013f58f794" }, "url":"/show?id=87a4003e" }, ... ], "work":{ "id":"85aa0c385a", "title":"PARATIISI", "url":"/work?id=85aa0c385a" }, "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=85aa0c385a&method=topMunicipalities
    Example response:
    { "topMunicipalities":[ { "municipality":{ "name":"EURA", "url":"/municipality?name=EURA" }, "count":6 }, { "municipality":{ "name":"JOENSUU", "url":"/municipality?name=JOENSUU" }, "count":6 }, ... ], "work":{ "id":"85aa0c385a", "title":"PARATIISI", "url":"/work?id=85aa0c385a" }, "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=85aa0c385a&method=topVenues
    Example response:
    { "topVenues":[ { "venue":{ "id":"82a70d3f", "name":"SOKOS HOTEL KIMMEL", "url":"/venue?id=82a70d3f" }, "count":6 },{ "venue":{ "id":"85a70b3e", "name":"IKAALISTEN KYLPYLÄ", "url":"/venue?id=85a70b3e" }, "count":4 }, ... ], "work":{ "id":"85aa0c385a", "title":"PARATIISI", "url":"/work?id=85aa0c385a" }, "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":"80a508395c", "title":"AIKUISTEN MIESTEN JOULU", "url":"/work?id=80a508395c" }, { "id":"81a30e305d", "title":"AINOA OIKEA JOULU", "url":"/work?id=81a30e305d" }, ... ], "response_meta":{ ... } }

Author

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

Example request:
/author?id=85a20c3e5af69c
Example response:
{ "author":{ "id":"85a20c3e5af69c", "firstname":"ELVIS AARON", "lastname":"PRESLEY", "works":{ "url":"/author?id=85a20c3e5af69c&method=works", "count":9 }, "topWorks":{ "url":"/author?id=85a20c3e5af69c&method=topWorks" }, "topVenues":{ "url":"/author?id=85a20c3e5af69c&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":"80a40a3e5cf692", "firstname":"", "lastname":"!K7 PUBLISHING GMBH", "url":"/author?id=80a40a3e5cf692" }, { "id":"83a5013d59f293", "firstname":"", "lastname":"100 SONGS", "url":"/author?id=83a5013d59f293" }, ... ], "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=85a20c3e5af69c
    Example response:
    { "author":{ "id":"85a20c3e5af69c", "firstname":"ELVIS AARON", "lastname":"PRESLEY", "works":{ "url":"/author?id=85a20c3e5af69c&method=works", "count":9 }, "topWorks":{ "url":"/author?id=85a20c3e5af69c&method=topWorks" }, "topVenues":{ "url":"/author?id=85a20c3e5af69c&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=85a20c3e5af69c&method=works
    Example response:
    { "works":[ { "id":"8da208", "title":"AMAZING GRACE", "url":"/work?id=8da208" }, { "id":"80a50c38", "title":"DON'T BE CRUEL", "url":"/work?id=80a50c38" }, ... ], "author":{ "id":"85a20c3e5af69c", "firstname":"ELVIS AARON", "lastname":"PRESLEY", "url":"/author?id=85a20c3e5af69c" }, "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=85a20c3e5af69c&method=topWorks
    Example response:
    { "topWorks":[ { "work":{ "id":"82a70e3f", "title":"MELKEIN HALVAANNUIN", "url":"/work?id=82a70e3f" }, "count":208 }, ... ], "author":{ "id":"85a20c3e5af69c", "firstname":"ELVIS AARON", "lastname":"PRESLEY", "url":"/author?id=85a20c3e5af69c" }, "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=85a20c3e5af69c&method=topVenues
    Example response:
    { "topVenues":[ { "venue":{ "id":"87a40e30", "name":"M/S VIKING GRACE", "url":"/venue?id=87a40e30" }, "count":46 }, { "venue":{ "id":"87a40d39", "name":"M/S FINLANDIA", "url":"/venue?id=87a40d39" }, "count":32 }, ... ], "author":{ "id":"85a20c3e5af69c", "firstname":"ELVIS AARON", "lastname":"PRESLEY", "url":"/author?id=85a20c3e5af69c" }, "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":"86a20c3f5ef69d", "firstname":"JEAN", "lastname":"SIBELIUS", "url":"/author?id=86a20c3f5ef69d" }, "count":629 }, ... ], "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=2015-06-28
Example response:
{ "date":{ "date": "2015-06-28", "eventCount": 91, "startDate": { "url": "/date?startDate=2015-06-28", "count": 91 }, "month": { "url": "/date?month=6", "count": 3903 }, "weekday": { "url": "/date?weekday=1", "count": 3880 } } }

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":"2015-01-01", "eventCount":88, "url":"/date?date=2015-01-01" }, { "date":"2015-01-02", "eventCount":85, "url":"/date?date=2015-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=2015-06-28
    Example response:
    { "date":{ "date": "2015-06-28", "eventCount": 91, "startDate": { "url": "/date?startDate=2015-06-28", "count": 91 }, "month": { "url": "/date?month=6", "count": 3903 }, "weekday": { "url": "/date?weekday=1", "count": 3880 } } }
  • /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=2015-06-28
    Example response:
    { "events":[ { "id":"85a6093d59f897", "name":"", "startDate":"2015-06-28", "endDate":"2015-06-28", "url":"/event?id=85a6093d59f897" }, { "id":"85a6093e5cf493", "name":"", "startDate":"2015-06-28", "endDate":"2015-06-28", "url":"/event?id=85a6093e5cf493" }, ... ], "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":"85a6093f59f694", "name":"", "startDate":"2015-06-01", "endDate":"2015-06-10", "url":"/event?id=85a6093f59f694" }, { "id":"85a6093e5cf59d", "name":"", "startDate":"2015-06-01", "endDate":"2015-06-01", "url":"/event?id=85a6093e5cf59d" }, ... ], "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":"85a10f315df897", "name":"", "startDate":"2015-01-02", "endDate":"2015-01-02", "url":"/event?id=85a10f315df897" }, { "id":"85a1003f5bf395", "name":"", "startDate":"2015-01-02", "endDate":"2015-01-02", "url":"/event?id=85a1003f5bf395" }, ... ], "response_meta":{ ... } }