Palvelun rajapintakäyttö

Avoindata-palvelun käyttäminen API:n kautta

Avoimen tiedon (datan) tuottajilla on usein tarve hakea ja päivittää tietoaineistoja tai niitä kuvaavia metatietoja säännöllisesti. Kun tiedot ovat valmiina tietojärjestelmässä, kannattaa toistuvat rutiinit automatisoida palvelun rajapintojen avulla.

Avoindata-palvelu sisältää REST/JSON-rajapinnat, joiden päälle nykyiset käyttöliittymät on rakennettu. Kaikki Avoindata-palvelussa olevat tiedot on saatavilla rajapintojen avulla.

Palvelun tavoite on, että mahdollisimman moni avoimen datan tuottaja julkaisisi automaattisesti päivittyvät tiedot palvelun rajapintojen avulla. Automaattiset päivitykset pitävät tiedot paremmin ajan tasalla, datan laatu nousee ja hyödyllisyys kasvaa.

Metatietojen ja tietoaineistojen hakeminen rajapinnan kautta

Alle on koottu joidenkin esimerkkikyselyjen vastauksia. Tietoaineistojen ja metatietojen hakemiseen et tarvitse API-avainta/API-tokenia.

API-avain ja API-tokenit

Jos haluat muokata tai lisätä tietoja rajapintojen avulla, tarvitset API-avaimen/API-tokenin. Alta löydät ohjeet API-avaimen löytämiseen ja API-tokenin luomiseen Avoindata-palvelussa.

Avoindatan käyttämässä uudessa CKAN-versiossa API-avaimen rinnalle tuli käyttöön API-tokenit. Tällä hetkellä voit käyttää kumpaa tahansa, mutta CKANin seuraavat versiot eivät enää tue API-avaimen käyttöä, vaan CKANissa siirrytään käyttämään pelkästään API-tokeneita. 

API-avain

Huom.

API-avain on henkilökohtainen, ja se luodaan jokaiselle käyttäjälle erikseen. Älä siis luovuta API-avaintasi muille.

Saat API-avaimen, kun luot käyttäjätunnuksen palveluun. API-avain löytyy käyttäjäprofiilisi sivulta palvelusta, kun olet sisäänkirjautunut.

  1. Kirjaudu sisään palveluun. Jos sinulla ei ole vielä käyttäjätunnusta, rekisteröidy ensin palveluun.​​

  2. Valitse sivun yläreunasta oma käyttäjätunnuksesi (tässä esimerkissä se on "testikäyttäjä").

    Pääset omalle profiilisivullesi valitsemalla käyttäjänimesi.
     

  3. Profiilisivusi vasemmassa reunassa olevan palkin alin kenttä kertoo API-avaimesi, joka on tyyliltään UUID-koodi (esimerkiksi 123e4567-e89b-12d3-a456-426655440000). Alla olevasta esimerkkikuvasta API-avain on piilotettu tietoturvasyistä. 

    Löydät API-avaimen profiilisivultasi käyttäjätunnuksesi tiedoista. API-avain on kirjaimista ja numeroista koostuva sarja,

API-token

Tokenit toimivat API-avaimen tapaan. Saat luotua API-tokenin seuraamalla alla olevia ohjeita.

1. Navigoi omaan profiiliisi ja valitse API-tokenit välilehti luodaksesi API-tokenin.

API-token luodaan omassa profiilissa API tokenit -välilehdellä.

2. Anna tokenille nimi ja valitse Luo API token.API-tokenille annetaan ensin nimi, jonka jälkeen painetaan Luo API token -painiketta.

3. Sivun yläreunaan tulee ilmoitus, josta voit kopioida oman API-token koodisi. Ota koodi talteen, sillä sitä ei saa palautettua, jos kadotat sen, vaan sinun täytyy luoda uusi token.

API-tokenit välilehdellä voit poistaa ja luoda uusia tokeneita. Poistaminen lopettaa tokenin toiminnan.

    API-avaimen hyödyntäminen

    Tietojen päivittämiseen, lisäämiseen ja muokkaamiseen tarvitaan API-avain. API-avain sisällytetään http-kutsun HEADER-osaan joko "Authorization" tai "X-CKAN-API-Key" merkinnällä varustettuna.

    Esimerkiksi Python-koodissa API-avainta käytetään näin:

    request = rllib2.Request('http://avoindata.fi/data/api/3/action/dashboard_activity_list ') request.add_header('Authorization', 'XXX') response_dict = json.loads(urllib2.urlopen(request, '{}').read())

    Saat API-avaimen, kun rekisteröidyt palveluun. Oma API-avain (field_ckan_api_key) löytyy omasta käyttäjäprofiilista. API-avaimet ovat tyyliltään UUID-koodeja (esimerkiksi 123e4567-e89b-12d3-a456-426655440000).

    Esimerkkiavaimella yllä kuvattu Python-koodi menisi näin:

    request = urllib2.Request('http://avoindata.fi/data/api/3/action/dashboard_activity_list') request.add_header('Authorization', '123e4567-e89b-12d3-a456-426655440000') response_dict = json.loads(urllib2.urlopen(request, '{}').read())

    Tietoaineiston lisääminen rajapinnan kautta

    Tietoaineiston lisäämiseen tarvitset API-avaimen.

    Tietoaineiston lisäämiseen tarvittava rajapinta on osoitteessa:

    http://avoindata.fi/data/api/rest/dataset/osm

    Jos lisäys onnistuu, vastaa rajapinta seuraavalla tavalla (esimerkki):

    {"id": "a3dd8f64-9078-4f04-845c-e3f047125028", "name": "osm", "title": "Open Street Map", …}

    Tietoaineiston päivittäminen rajapinnan kautta

    Tietoaineiston päivittämiseen tarvitset API-avaimen.

    Esimerkki, miten tietoaineiston päivittäminen onnistuu:

    http --json POST http://avoindata.fi/data/api/3/action/resource_update id=<resource id> upload=@updated_file.csv Authorization:<api key>

    Jos päivittäminen ei onnistu, niin API vastaa näin:

    { "success": false

    "error":

        { "__type": "Not Found Error",

          "message": "Not found"

        },

    "help": "...",

    }

    JSON selaimessa

    JSON (JavaScript Object Notation) on yksinkertainen avoimen standardin dataformaatti tiedonvälitykseen. Nimestään huolimatta se on JavaScript-ohjelmointikielestä riippumaton.

    JSON-dataformaatti ei aina näytä internet-selaimessa selkeältä. Selaimiin on kuitenkin saatavilla erilaisia laajennuksia, jotka muotoilevat sen ihmiselle helpommin luettavaa muotoon.

    Selainlaajennoksia JSON:n muotoiluun

    Alla on esimerkki oikein muotoillusta JSON-dataformaatista, josta ihmisen on helppo erottaa tietosisältö.
    Esimerkki muotoillusta JSON-dataformaatista, josta ihmisen on helppo erottaa tietosisältö.

    Lisädokumentaatio

    Tutustu myös CKANin kattavaan API-dokumentaatioon (englanniksi)

    Päivitetty: 29.9.2023