Bruke API-et

Gjennomgåtte eksempler for THMIs offentlige API — autentisering, lesing av verdier, historikkspørringer, feilhåndtering og formater.

Denne siden er den praktiske følgesvennen til listen over endepunkter: hvordan du autentiserer, hvordan kroppen i en historikkspørring ser ut, hvordan tidsstempler og feil er utformet, og hvordan du velger mellom JSON og CSV. For den fullstendige, maskinlesbare kontrakten bruker du OpenAPI-spesifikasjonen.

Autentisering

Send tilgangstokenet ditt som et bearer-token i hver forespørsel. Headeren må begynne med Bearer — ingenting annet godtas, og det finnes ingen reserveløsning med spørringsparameter:

curl https://<your-cloud-host>/api/v1/projects/list \
  -H "Authorization: Bearer <your-token>"

En forespørsel med manglende eller feilformatert Authorization-header avvises med 401 Unauthorized før den når noen prosjektdata. Et gyldig token som ikke har fått tilgang til prosjektet eller ressursen du ber om, får 403 Forbidden.

Lese en gjeldende verdi

Gjeldende verdier hentes med vanlige GET-forespørsler. Hent én tagg etter banen:

curl "https://<your-cloud-host>/api/v1/<projectId>/tag/values/by-path?tagPath=Building/Boiler/SupplyTemp" \
  -H "Authorization: Bearer <your-token>"

Alt unntatt historikk og CSV-eksport er GET — se Endepunkter for hele settet (prosjekter, tagger, verdier, sider, tidssoner).

Spørre etter historikk

Historikk er den eneste lesingen som bruker POST — ikke fordi den endrer noe, men fordi spørringen er for stor for en URL. Kroppen inneholder tidsrommet, taggene og hvordan de skal aggregeres. Velg endepunkt ut fra hvordan du identifiserer tagger (by-path eller by-id), og svarformatet med det siste leddet i banen (json eller csv):

curl -X POST "https://<your-cloud-host>/api/v1/<projectId>/history/aggregate/by-path/json" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "timeFrom": 1572548400000,
    "timeTo": 1574239662847,
    "timeZone": "Europe/Stockholm",
    "groupingType": "HOURS",
    "valueType": "ACTUAL",
    "tagList": ["Building/Boiler/SupplyTemp", "Building/Boiler/ReturnTemp"]
  }'

For by-id legger du tagg-ID-er i tagList i stedet for baner. Det utfasede …/history/aggregate/{format} (uten by-path/by-id) oppfører seg som by-id.

Tidsstempler

Alle tidsstempler — timeFrom/timeTo du sender, og tidspunktene for punktene du får tilbake — er heltall i epoch-millisekunder (UTC), ikke ISO-strenger. timeZone påvirker bare hvordan intervallene justeres og merkes, ikke enhetene. Konverter til og fra din egen sone på din side.

Formater

• Svarene er i JSON som standard. Historikk og eksporten av den gir også CSV, og sider gjengis som SVG.
• Formatet velges med banen, ikke med en Accept-header — det avsluttende /json eller /csv på historikkendepunktene bestemmer det. Ber du om csv, strømmes de samme dataene som en CSV-nedlasting.

Feil

Feil returneres som en liten JSON-konvolutt med status satt til fail:

{
  "status": "fail",
  "message": "A human-readable explanation",
  "code": "optional_error_code"
}

HTTP-statusen forteller deg kategorien: