Application programming interface (API)

Data stored in the Finnish Research Infrastructures -service can be accessed through an interfaces described on this page.

Why use an API?

Using the research infrastructure information stored the service through an API has the following advantages:

  • A centralized and easily updatable information source about research infrastructures
  • Unified format and validity: descriptive metadata given by infrastructures themselves presented in a format designed by both researchers and funders
  • Enables data enrichment by combining multiple sources
  • Reduces redundant data input effort through automatization

 

Technical description and instructions

Below is a simplified description of the schema, which contains four main entities in the data: Infrastructures, Services, Organizations and Contact Information.

A more detailed schema documentation is available in the Interoperability descriptions -service: http://iow.csc.fi/model/tipa/

Each of the four entities have related methods, which can be used to query the information within the databank. The API is implemented on Liferay's JSONWS tool and the responses are given in JSON-format. Queries can be made with, for example, the curl-application, through an inline URL-reference and Liferay's user interface.

The API is available in: http://avaa.tdata.fi/api/jsonws?contextPath=/tupa-portlet

Functionality of the API can be queried by: curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Helper/get-capabilities

A JavaDoc -like documentation is available in: http://avaa.tdata.fi/adata/tupa/

Questions and comments are welcomed in the address: avaa (at) csc.fi.

Examples

A few examples of simple API queries are explained below.

Attention: Dividers for lists of parameters are either commas (",") or semicolons (";"). Strings of characters should be enclosed by quotation marks  (" "" " or " '' "). In the examples below, three dots or an ellipsis ("…") signify a section left out for the sake of readability.

Entity: Organization (TpOrganisation)

Method:  get-organisations-by-organisations-ids (getOrganisationsByOrganisationsIds)

Explanation: returns a list of Organisations based on given IDs

UI: http://avaa.tdata.fi/api/jsonws?contextPath=/tupa-portlet&signature=%2Ftupa-portlet%2FOrganisations%2Fget-organisations-by-organisations-ids-1-organisationsIds

Parameters: Id numbers of organizations

Parameter type: an arbitrary length array of positive integers

URL-query example for organizations with id numbers 1 (one) and 3 (three):

  1. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Organisations/get-organisations-by-organisations-ids/organisations-ids/1%2C3
  2. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Organisations/get-organisations-by-organisations-ids/organisations-ids/1%3B3
  3. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Organisations/get-organisations-by-organisations-ids/organisations-ids/%221%22%2C%223%22
  4. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Organisations/get-organisations-by-organisations-ids/organisations-ids/'1'%2C'3'

Result:

[
  {
    "contactsIds": [26, 27],
    "country": "FI",
    "id": 1,
    "infrastructuresIds": [18],
    "isni": "0000 0001 2198 1512",
    "motherOrganisationsIds": 0,
    "name_EN": "University of Turku",
    "name_FI": "Turun yliopisto",
    "servicesIds": [119, ... , 125]
  },
  {
    "contactsIds": [1, ... , 40],
    "country": "GB",
    "id": 3,
    "infrastructuresIds": [1, 17, 21],
    "isni": "",
    "motherOrganisationsIds": 0,
    "name_EN": "United Kingdom",
    "name_FI": "Yhdistynyt kuningaskunta",
    "servicesIds": [1, ... , 140]
  }
]

 

Entity: Infrastructure (TpInfrastructure)

Method: get-infrastructures-by-urns (getInfrastructuresByUrns)

Explanation: returns a list of Infrastructures based on given URN-identifiers

UI: http://avaa.tdata.fi/api/jsonws?contextPath=/tupa-portlet&signature=%2Ftupa-portlet%2FInfrastructures%2Fget-infrastructures-by-urns-1-infrastructuresUrns

Parameters: infrastructure URN-identifiers

Parameter type: an arbitrary length array of character strings

URL-query example for infrastructures with URN-identifiers "urn:nbn:fi:research-infras-201607251" and "urn:nbn:fi:research-infras-201607251":

  1. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Infrastructures/get-infrastructures-by-urns/infrastructures-urns/%22urn%3Anbn%3Afi%3Aresearch-infras-201607251%22%2C%20%22urn%3Anbn%3Afi%3Aresearch-infras-201607253%22
  2. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Infrastructures/get-infrastructures-by-urns/infrastructures-urns/'urn%3Anbn%3Afi%3Aresearch-infras-201607251'%2C%20'urn%3Anbn%3Afi%3Aresearch-infras-201607253'

Result:

[
  {
    "contactsIds": [26, 27],
    "country": "FI",
    "id": 1,
    "infrastructuresIds": [18],
    "isni": "0000 0001 2198 1512",
    "motherOrganisationsIds": 0,
    "name_EN": "University of Turku",
    "name_FI": "Turun yliopisto",
    "servicesIds": [119, ... , 125]
  },
  {
    "contactsIds": [1, ... , 40],
    "country": "GB",
    "id": 3,
    "infrastructuresIds": [1, 17, 21],
    "isni": "",
    "motherOrganisationsIds": 0,
    "name_EN": "United Kingdom",
    "name_FI": "Yhdistynyt kuningaskunta",
    "servicesIds": [1, ... , 140]
  }
]

 

Entity: Service (TpServize)

Method: get-services-by-location (getServicesByLocation)

Explanation: returns a list of Services, which are located within approximately 1 km radius of given coordinates (depending on the service's location).

UI: http://avaa.tdata.fi/api/jsonws?contextPath=/tupa-portlet&signature=%2Ftupa-portlet%2FServices%2Fget-services-by-location-2-latitude-longitude

Parameters: service location latitude, service location longitude

Parameter types: latitude in double, longitude in double

URL-query example for services located near coordinates "60.175538000000000000" and "24.955310000000000000":

  1. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Services/get-services-by-location/latitude/60.175538000000000000/longitude/24.955310000000000000

Result:

[
  {
    "address": "Kaikukatu 4",
    "city": "Helsinki",
    "contactsIds": [3, 67],
    "description_EN": "Consortium acquiring centrally scholarly journals, books, reference books and databases in electronic format",
    "description_FI": "Konsortio, joka hankkii keskitetysti tieteellisiä e-lehtiä, e-kirjoja, hakuteoksia ja tietokantoja",
    "id": 8,
    "infrastructuresIds": [3],
    "lat": 60.182538,
    "locationTypes": [],
    "lon": 24.96031,
    "name_EN": "Acquisition of electronic publications",
    "name_FI": "Verkkoaineistojen hankinta",
    "organisationsIds": [4, 7],
    "serviceTypes": [],
    "url": "http://www.nationallibrary.fi/en/libraries/finelib.html"
  }
]

 

Entity: Contact (TpContact)

Method: get-all-contacts (getAllContacts)

Explanation: returns the whole list of all Contacts

UI: http://avaa.tdata.fi/api/jsonws?contextPath=/tupa-portlet&signature=%2Ftupa-portlet%2FContacts%2Fget-all-contacts-0

Parameters: (no parameters)

URL-query example for all available Contact Informationkyselyesimerkki kaikille saatavilla oleville Yhteystiedoille:

  1.     curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Contacts/get-all-contacts

Vastaus:

[
  {
    "description_EN": "",
    "description_FI": "",
    "email": "erja.esimerkki@yliopisto.fi",
    "firstName": "Erja",
    "id": 1,
    "infrastructuresIds": [1],
    "lastName": "Esimerkki",
    "organisationsIds": [2, 3],
    "phone": "",
    "servicesIds": [1, 2, 3, 4, 5],
    "title": "professori",
    "url": ""
  },
  ... ,
  {
    "description_EN": "",
    "description_FI": "",
    "email": "eini.esimerkki@university.fi",
    "firstName": "Eini",
    "id": 80,
    "infrastructuresIds": [15],
    "lastName": "Esimerkki",
    "organisationsIds": [
      4
    ],
    "phone": "040-653 1133",
    "servicesIds": [89, 90, 91, 92, 93, 94, 95, 96, 97],
    "title": "Johtaja",
    "url": ""
  }
]