Avoindata.fi:n käyttö rajapinnan (API) kautta

Yksittäisiä tietoaineistoja käytetään usein graafisen käyttöliittymän avulla. Avoimen tiedon (datan) tuottajilla on kuitenkin usein tarve hakea, päivittää tai muokata tietoaineistoja tai niitä kuvaavia metatietoja säännöllisesti. Silloin kannattaa automatisoida toistuvat rutiinit palvelun 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 sen hyödyllisyys kasvaa.

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

Avoindata.fi:n käyttäminen API:n kautta

API-avain

Jos haluat muokata tai lisätä tietoja rajapintojen avulla, tarvitset API-avaimen. Sen saat, 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 sinulle ei ole vielä käyttäjätunnusta, rekisteröidy palveluun.

    Kirjaudu ensin avoindata.fi:hin käyttämällä Kirjaudu-painiketta.
     

  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. Päädyt profiilisivullesi. Sivun vasemmassa reunassa olevan palkin alin kenttä kertoo API-avaimesi. Tästä esimerkistä se on piilotettu tietoturvasyistä. API-avain on henkilökohtainen, ja se luodaan jokaiselle käyttäjälle erikseen.

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

Metatietojen ja tietoaineistojen hakeminen rajapinnan kautta

Hae kaikkien palvelussa olevien tietoaineistojen nimet (ID:t):
https://www.avoindata.fi/data/api/3/action/package_list

Hae palvelussa olevat datakategoriat:
https://www.avoindata.fi/data/api/3/action/group_list

Hae palvelussa käytetyt tietoaineistojen asiasanat:
https://www.avoindata.fi/data/api/3/action/tag_list

Hae yksittäinen tietoaineisto:
http://avoindata.fi/data/api/3/action/package_show?id=id
Jossa esimerkiksi id voisi olla “aluesarjat-a04s-hki-askan-talotyyppi”, jolloin kysely toimisi näin:
http://avoindata.fi/data/api/3/action/package_show?id=aluesarjat-a04s-hki-askan-talotyyppi

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 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 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 tarvitsen 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.

Esimerkki: Selainlaajennoksia JSON:n selventämiseksi

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


Lisädokumentaatio

Kattavan dokumentaation englanninkielisenä löydät osoitteista:
https://docs.ckan.org/en/2.8/api/
https://docs.ckan.org/en/ckan-1.7.4/api-tutorial.html