Tietoaineistojen ja metatietojen hakemiseen et tarvitse API-avainta/API-tokenia.

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

Jos haluat muokata tai lisätä tietoja rajapintojen avulla, tarvitset API-avaimen/API-tokenin.

Avoindata.fi:n 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

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 sinulle ei ole vielä käyttäjätunnusta, rekisteröidy palveluun.
   
   
    

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

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ä luovuta API-avaintasi muille. 
   
   

 API-token

Tokenit toimivat API-avaimen tapaan.  

1. Luodaksesi API-tokenin navigoi omaan profiiliisi ja valitse API-tokenit välilehti.

2. Anna tokenille nimi ja valitse Luo API token.

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.  

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ää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ä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 (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.

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