Etsin API

Etsin may be also be used via an API (Application Programming Interface). Etsin supports standard CKAN API commands. In addition, Etsin supports addition and deletion of dataset editors with dataset_editor_add and dataset_editor_delete, respectively. To add a dataset editor, provide also attributes: name (dataset's name), role (usually editor) and username (user login to add)

The metadata model of Etsin is more complex than the default model in CKAN. Beneath is an example of a dataset that can be created in Etsin, using Curl. Note, that you can get your API key from your profile page.

API use example

curl "https://etsin.avointiede.fi/api/3/action/package_create" -d '{"owner_org": "00000000-0000-0000-0000-000000000000", "agent": [{"organisation": "Yliopisto. Tiedekunta. Laitos.", "role": "author", "name": "Elvira Example", "id": "http://orcid.org/example"}, {"organisation": "University. Faculty. Institution.", "role": "author", "id": "http://orcid.org/secondexample", "name": "Firstname Surname "}, {"organisation": "Universitet. Fakultet. Institution.", "role": "author", "name": "Förnamn Efternamn", "id": "http://orcid.org/tredjeexemplet"}, {"organisation": "Yliopisto. Tiedekunta. Laitos.", "role": "contributor", "id": "http://orcid.org/esimerkki", "name": "Etunimi Sukunimi"}, {"URL": "http://projektin.kotisivunosoite.ti", "organisation": "Rahoittanut säätiö", "role": "funder", "fundingid": "Rahoitustunniste-123", "name": "Projektin nimi"}, {"organisation": "Second funder", "role": "funder", "fundingid": "Funding-id-123"}, {"role": "owner", "name": "Omistaja tulee tähän, hyvä jos on organisaatio, mutta voi olla vaikka orcid"}, {"role": "owner", "name": "It is good if there is an institutional contact given here as owner, but can also be an ORCID"}, {"role": "owner", "name": "Här anges ägaren, det är bra om det är en institution men kan vara person, gärna ORCID"}], "temporal_coverage_end": "2017-02-22", "pids": [{"type": "primary", "id": "https://primary.identifier.com/1234"}, {"relation": "isMetadataFor", "type": "relation", "id": "https://urn.fi/this.dataset.has.an.orginal.metadataset/here"}, {"type": "relation", "relation": "isNewVersionOf", "id": "http://also_a_previous_version_can_be_found_with_DOI"}], "event": [{"type": "collection", "who": "Conny Collector", "when": "2012", "descr": "Conny collected the data"}], "discipline": "http://www.yso.fi/onto/okm-tieteenala/ta113", "algorithm": "MD5", "format": "csv, xml", "availability": "direct_download", "direct_download_URL": "https://data.com/download/1234",  "license_id": "ODC-PDDL-1.0", "tag_string": "esimerkki,example,http://www.yso.fi/onto/koko/p34060,keyword,kuvailu,metatiedot,tutkimusaineistot,ämnesord,https://www.yso.fi/onto/koko/p36376,https://www.yso.fi/onto/koko/p73004", "title": "{\"fin\": \"Esimerkkiaineisto : Aineiston nimi tulee tähän, se on pakollinen tieto ainakin yhdellä kielellä.\", \"swe\": \"Exempelmaterialet :  Titeln på svenska kommer här. Det är ett obligatoriskt att ha en titel på minste ett språk.\", \"eng\": \"Example dataset : Title here : at least one language version is compulsory\"}", "temporal_coverage_begin": "2017-02-21T01:22:34Z",  "private": false, "mimetype": "application/atomsvc+xml", "geographic_coverage": "Keravanjoki,Ii,Itämeri,China", "language": "fin,eng,swe", "checksum": "this-is-a-checksum-hash", "notes": "{\"fin\": \"Tähän tulee aineiston vapaa kuvaus suomeksi\", \"swe\": \"En fri beskrivning av datasetet kommer här\", \"eng\": \"Here you should find a free text description about the dataset.\"}", "contact": [{"URL": "http://etusivu.fi/yhteystiedot", "phone": "+358 123 45789", "email": "etunimi.sukunimi@organisaatio.fi", "name": "Etunimi Sukunimi von Rekisterinpitäjä"}], "citation": "Tutkimusaineistoni, 2015-01-01, Matti Meikäläinen (tekijä), John Smith (tekijä), Martha Smith (tekijä), Malla Meikäläinen (jakelija), Jake Smith (jakelija), 2016. https://projektinkotisivu.fi", "accept-terms": "True", "version": "2017-01-01T12:00:00Z"}' -H "Authorization: MY_PRIVATE_KEY"
Description value of the pids field
The research dataset does not have a persistent identifier In this case the field is not needed at all. Etsin automatically generates the primary pid for you.
The research dataset has a persistent identifier (URN, DOI or similar) [{"id": "http://doi.org/xyz", "type": "primary"}]
The research dataset does not have a persistent identifier but a previous version of the dataset exists. Etsin will generate a new identifier for the new dataset and the relation to the previous version should be expressed like this. Relations between versions are expressed with the values isNewVersionOf and isPreviousVersionof. [{"id": "urn:nbn:fi:org-xyz", "type": "relation", "relation": "isNewVersionOf"}]
In this example the research dataset has a persistent identifier and it is a part of a bigger research dataset. Hierarchic relations are expressed with isPartOf and hasPart. [{"id": "http://doi.org/xyz", "type": "primary"}, {"id": "urn:nbn:fi:org-xyz", "type": "relation", "relation": "isPartOf"}]
 

Using the results from the previous command, you can list details of an organization with a command

 

For example

 

You can search for research datasets using the package_search function. You can combine different types of searches with this command, just like in the web user interface. For instance to display all datasets linked to an organization, use command:

 

Note that the parameter is the organization's id which was attained earlier from the organization_show function.

 

OAI-PMH Service

Metadata can also be harvested with OAI-PMH requests at https://etsin.avointiede.fi/oai in the following ways:

  • data about groups (ListSets, currently only organizations)
  • dataset titles (ListIdentifiers)
  • specific record (GetRecord)
  • all records (ListRecords)

Examples:

The requests ListSets, ListIdentifiers and ListRecords cut the list into pieces and delivers only one piece at a time. The following piece can be fetched by giving the resumptionToken that is given in the end of the result as parameter in the following request.

Example:
 

 

With the following parameters you can limit the number of records you get: