-
Notifications
You must be signed in to change notification settings - Fork 0
Aineistopalvelu
Dokumentaatio on muuttanut. Ajantasainen dokumentaatio löytyy osoitteesta https://github.com/solita/ara-etp/wiki.
ARA Energiatodistusrekisterin aineistopalvelu tarjoaa rajapinnan energiatodistusten tietojen hakemiseen koneluettavassa muodossa.
Aineistojen käyttämiseen tarvitaan Asumisen rahoitus- ja kehittämiskeskuksen (ARA) myöntämä rajapinta-avain ja rajapinnan URL. Alla olevassa esimerkissä:
- rajapinta-avain:
eWh0ZXlzaGVua2lsb0BvcmdhbmlzYWF0aW8uZmk6YWh5MFhhaXRoYTFwbzdpdmFlM3Rob28zbWFpR2FpOE9vRGllOGhlaTdyYWhwaGV1cDU= - URL:
https://example.energiatodistusrekisteri.fi/api/external/aineistot/1/energiatodistukset.csv
Aineisto haetaan kahdessa vaiheessa. Ensiksi tehdään HTTPS GET -pyyntö ARAn toimittamaan URL-osoitteeseen, jossa on Authorization -headeriin merkitty arvoksi "Basic ${API_KEY}", eli esimerkin tapauksessa:
Basic eWh0ZXlzaGVua2lsb0BvcmdhbmlzYWF0aW8uZmk6YWh5MFhhaXRoYTFwbzdpdmFlM3Rob28zbWFpR2FpOE9vRGllOGhlaTdyYWhwaGV1cDU=
Jos API key on oikein ja voimassa, saadaan vastauksena HTTP 302 -statuksella varustettu redirect -viesti.
Tämän location-header sisältää allekirjoitetun URL:n, jonka kautta aineiston saa ladattua. Lataus tulisi aloittaa välittömästi, koska allekirjoitus on voimassa noin minuutin.
Jos HTTP-asiakasohjelma seuraa HTTP 302 –uudelleenohjauksia automaattisesti, ei aineistopalveluun liittyjän välttämättä tarvitse tehdä muuta aineiston lataamiseksi.
Jos HTTP-asiakasohjelma ei automaattisesti seuraa HTTP 302 -uudelleenohjausta, palveluun liittyjän tulee toteuttaa se niin, että lataus aloitetaan allekirjoituksen voimassaoloajan sisällä.
Esimerkin tapauksessa curl -työkalulla lataaminen tehtäisiin komennolla
curl –L \
-H "Authorization: Basic eWh0ZXlzaGVua2lsb0BvcmdhbmlzYWF0aW8uZmk6YWh5MFhhaXRoYTFwbzdpdmFlM3Rob28zbWFpR2FpOE9vRGllOGhlaTdyYWhwaGV1cDU=" \
https://example.energiatodistusrekisteri.fi/api/external/aineistot/1/energiatodistukset.csvPowerShell -kielellä näin:
$uri = 'https://example.energiatodistusrekisteri.fi/api/external/aineistot/1/energiatodistukset.csv'
$apiKey = 'eWh0ZXlzaGVua2lsb0BvcmdhbmlzYWF0aW8uZmk6YWh5MFhhaXRoYTFwbzdpdmFlM3Rob28zbWFpR2FpOE9vRGllOGhlaTdyYWhwaGV1cDU='
Invoke-WebRequest -Uri "$uri" -OutFile energiatodistukset.csv -Headers @{'authorization'="Basic $apiKey"}Python-ohjelmointikielellä lataaminen onnistuu esimerkiksi näin:
import urllib.request
# ARA will supply the correct KEY and URL to be used
KEY = "YXdlc29tZWFzaWFrYXNAZXhhbXBsZS5jb206YXNrZGF1d0FTQVN3VzM0MiUmNDQjIyEhcHBra3NzeQ=="
URL = "https://private.energiatodistusrekisteri.fi/api/external/aineistot/1/energiatodistukset.csv"
DEST = "my.csv"
def fetch_aineisto():
headers = {
"authorization": f"Basic {KEY}",
}
req = urllib.request.Request(URL, headers=headers)
response = urllib.request.urlopen(req)
contents = response.read()
with open(DEST, "wb") as f:
f.write(contents)
print(f"Received {len(contents)} bytes into {DEST}")Palvelun tuottama aineisto on CSV-muodossa niin, että kutakin energiatodistusta vastaa yksi rivi. Rivien sarakejoukko riippuu ladatun aineiston tyypistä. Ainestoja on tällä hetkellä tarjolla kolme erilaista.
Osassa sarakkeita sisältönä on vain tunnistenumero. Näiden selitteet löytyvät Luokittelut -sivulta.