API
Det finns ett enkelt API för att hämta senaste temperaturerna från temperatur.nu.
Aktuell API-version 1.16.
Data returneras i XML-format eller json-format
Support
För support på API-funktionen, använd Forumet på www.temperatur.nu.
Villkor
- Mjukvaran skall skrivas på ett sådant sätt att APIet inte automatiskt belastas med samma fråga oftare än var femte minut från en enskild klient. Klientid som bryter mot detta villkor kan komma att blockeras.
- Det måste mycket tydligt framgå att temperaturerna kommer från temperatur.nu.
- Där så är möjligt skall temperaturerna vara länkar till temperatur.nu.
- Temperatur.nus logotype skall finnas i applikationen, gärna så den tydligt syns när programmet används. Om detta ej är möjligt kan logotypen placeras där inställningar för applikationen görs.
- APIet får ej användas för att automatiskt samla in och lagra data längre än 24h.
- I de fall applikationen kommer att kosta pengar för användaren krävs särskild överenskommelse med temperatur.nu. Kontakta [email protected] för mer information.
- Förfrågningar till APIet kan signeras, från och med version 1.11 är osignerade förfrågningar är begränsade till ca 20/timma per klientid. Denna begränsning kommer efter hand att läggas in även på de äldre versionerna. Maila [email protected] för att att erhålla en signeringsnyckel för ditt klientid. När du ansöker om en signeringsnyckel måste du ange om du vill signera med sha1 eller md5. Läs mer om hur du signerar förfrågningarna längre ner på denna sida.
- Du skall skriva en beskrivning av din mjukvara i denna Wiki. På så sätt kommer fler intresserade att hitta din applikation. Klienter som inte finns beskrivna i Wikin kan komma att blockeras. Här finns en lista med kända klienter
Kort beskrivning
APIet är tänkt att användas av de som skapar extern mjukvara, tex applikationer för Iphone och Android. Målet är att APIet skall vara lättförståeligt och lätt att använda - feedback från användarna är av stor vikt för att kunna utveckla APIet!
Var finns APIet?
Du accessar APIet via http://api.temperatur.nu/tnu_1.<version>.php. ex: http://api.temperatur.nu/tnu_1.12.php
Parametrar
Generellta parametrar
| Parameter | Beskrivning | Kan ej användas med | Introducerad i API-version |
|---|---|---|---|
| json | Om angiven returneras data i json-format i stället för xml | 1.16 | |
| p | Anger för vilka orter data skall returneras - kommaseparerad lista. Utelämnas parametern returneras samtliga mätpunkter. | lat, lon, num | 1.0 |
| dc | Anger om decimalkomma skall användas i stället för decimalpunkt i fälten <temperatur>, <lat>, <lon> och <dist>. | 1.0 | |
| simple | Minimal output, returnerar endast <title>, <id> och <temp> | verbose | 1.0 |
| verbose | Returnerar alla fält för orten, se beskrivning nedan | simple | 1.0 |
| coordinates | Visar koordinaterna för valda orter. Kan användas tillsammans med simple för att kunna positionera orter på en karta utan att behöva hämta alla fält. | verbose | 1.0 |
| lat | Används tillsammans med lon och ev num. Det spelar inte någon roll om decimal- eller kommapunkt används. När dessa parametrar används returneras de num närmaste orterna, närmaste orten först. | p | 1.0 |
| lon | Används tillsammans med lat och ev num. Det spelar inte någon roll om decimal- eller kommapunkt används. När dessa parametrar används returneras de num närmaste orterna, närmaste orten först.. | p | 1.0 |
| num | Används tillsammans med lat och lon. Anger hur många orter som skall returneras. Standard är 1 och max är 5 (10 från v 1.12). | p | 1.0 |
| cb | CacheBust. Om denna parameter finns i urlen (&cb) kommer ett randomiserat värde att läggas till i slutet av graf-urlerna. Denna parameter kan användas för att se till att inte grafen cachas lokalt hos användaren eller i någon dåligt konfigurerad proxy mellan temperatur.nu och användaren. | 1.8 | |
| cli | Skall användas för att identifiera vilken klient som hämtar data. Ex "cli=tnu_widget". Från mitten av 2011 kommer signering av urlerna krävas i kombination med cli. Läs mer längre ner. | 1.1 | |
| sign | Skall APIet regelbundet måste URLerna signeras. Se information längre ner på denna sida. | 1.0 (tillagd i efterhand) |
Parametrar som är relaterade till att hämta statistik
| Parameter | Beskrivning | Kan ej användas med | Introducerad i API-version |
|---|---|---|---|
| data | Används för att hämta rådata för en mätpunkt specificerade med variabeln p. | graph, textfil | 1.16 |
| textfil | Används för att hämta länk till textfil med rådata för en mätpunkt specificerade med variabeln p. Ange parameter graddagar, dygnsmedel eller timmedel (ex textfil=graddagar) för att specificera vilket format textfilen ska ha. | graph, data | 1.16 |
| amm | Används för att hämta Average, Min & Max för upp till 5 (10 från v1.12) orter specificerade med variabeln p. | graph | 1.11 |
| daily | Används för att hämta dygnsmedel samt lägsta och högsta temperatur per dygn. En mätpunkt specificerad med variabeln p. | graph | 1.15 |
| span | Specificerar för vilket tidsperspektiv Average, Min & Max skall skapas. Giltiga värden är: 1day (standard), 1week, 1month, 1year. | start, end | 1.2 |
| shift_g | Anger om daily skall visa äldre data. Exempel: om span är 1month och shift_g är 1 hämtas data för föregående månad. Standard är 0. | start, end | 1.15 |
| start | Specificerar starttid för amm. Formatet är Y-m-d-H-i, ex 2011-01-30-12-31. | span | 1.11 |
| end | Specificerar sluttid för amm. Formatet är Y-m-d-H-i, ex 2011-01-30-12-31. Standard är nuvarande tid | span | 1.11 |
Parametrar som är relaterade till grafgenerering:
| Parameter | Beskrivning | Kan ej användas med | Introducerad i API-version |
|---|---|---|---|
| graph | Används för att generera en graf för upp till 5 orter specificerade med variabeln p. Anges variablen compare kommer orterna att läggas in i samma graf i stället för separata. | amm | 1.2 |
| span | Specificerar för vilket tidsperspektiv grafer skall skapas. Giltiga värden är: 1day (standard), 1week, 1month, 1year. | start, end | 1.2 |
| shift_g | Anger om grafen skall visa äldre data. Exempel: om span är 1day och shift_g är 1 visas en graf för igår, om shift_g är 2 visar grafen data för i förrgår etc. Standard är 0. | start, end | 1.5 |
| start | Specificerar starttid för graph eller amm. Formatet är Y-m-d-H-i, ex 2011-01-30-12-31. | span, shift_g, history | 1.11 |
| end | Specificerar sluttid för graph eller amm. Formatet är Y-m-d-H-i, ex 2011-01-30-12-31. Standard är nuvarande tid | span, shift_g, history | 1.11 |
| history | Används för att i grafen lägga in föregående periods temperatur. Visas temperaturen för det senaste dygnet visas föregående 24h i en annan färg etc. Kan förklarliga skäl endast användas med variabeln graph. | start, end | 1.12 |
| history_year | Används för att i grafen lägga in jämförelse med annat år. År anges med 4 siffror, ex 2013. Kan förklarliga skäl endast användas med variabeln graph. | start, end | 1.14 |
| verbose_g | Visar min/max/medel/senaste värde i grafen. Visar även när data senast hämtades för den valda orten. | 1.5 | |
| 1axis | Används för att endast visa temperaturskalan till vänster. Används med fördel i små grafer för att spara utrymme. | 1.6 | |
| fontsize | Anger hur stor texten skall vara. Observera att värdet inte kan relateras till vanliga textstorlekar, du måste därför testa dig fram. | 1.8 | |
| linewidth | Anger bredden på graflinjen. Giltiga värden 1 till 5. Även flyttal, ex 1.5, fungerar. Decimalkomma eller decimalpunkt spelar inte någon roll. | 1.7 | |
| x | Specificerar hur bred grafen skall vara. Giltiga värden är 150-2500. 300 är standard. | 1.2 (Tillåtna värden justerade i v 1.4,v 1.14) | |
| y | Specificerar hur hög grafen skall vara. Giltiga värden är 125-2500. 200 är standard. | 1.2 (Tillåtna värden justerade i v 1.4, v 1.14) | |
| color | Anger vilken/vilka färger linjer i grafen skall ha, kommasepararead lista. Standard är #FF0000,#AADDAA,#FFCC00. | 1.13 | |
| compare | Anger att order som skickats med p skall läggas in för jämförelse i samma graf. Om fler än tre orter anges måste även color definieras | 1.13 |
Beskrivning av returnerade fält
| Fält | Beskrivning | parameter som visar | parameter som döljer | Visas som standard | Introducerad i API-version |
|---|---|---|---|---|---|
| <title> | Mätpunktens namn på temperatur.nu | X | 1.0 | ||
| <id> | Mätpunktens id på temperatur.nu. Kan användas med parametern "p" för att hämta endast denna mätpunkts information | simple | X | 1.0 | |
| <temp> | Mätpunktens senaste temperatur. Om decimalkomma eller decimalpunkt skall användas styrs med parametern dc. | X | 1.0 | ||
| <lat> | Mätpunktens latitud i decimalt format. Om decimalkomma eller decimalpunkt skall användas styrs med parametern dc. | coordinates, verbose | 1.0 | ||
| <lon> | Mätpunktens longitud i decimalt format. Om decimalkomma eller decimalpunkt skall användas styrs med parametern dc. | coordinates, verbose | 1.0 | ||
| <lastUpdate> | Tidpunkt då informationen senast uppdaterades på temperatur.nu | verbose | 1.0 | ||
| <kommun> | Den kommun som mätpunkten ligger i. | verbose | 1.0 | ||
| <lan> | Det län som mätpunkten ligger i. | verbose | 1.0 | ||
| <sourceInfo> | En kort textsträng med information om vem som loggar temperaturen för mätpunkten | verbose | 1.8 | ||
| <forutsattning> | Textsträng med information om hur mätningarna sker - finns ej för alla mätpunkter och returernar om så är fallet ett tomt fält. | verbose | 1.16 | ||
| <url> | Url till mätpunktens temperatur och grafer på www.temperatur.nu | verbose | 1.0 | ||
| <dist> | Hur långt från de givna koordinaterna mätpunkten ligger. Enheten är kilometer. Om decimalkomma eller decimalpunkt skall användas styrs med parametern dc. | lat & lon | simple | 1.0 | |
| <graph> | Visar url till graph för orten. Observera att ny graf endast genereras när parametern graph används. Det går därför inte att lokalt cacha urlen i klienten. | graph (x, y, span, verbose_g, shift_g) | 1.2 | ||
| <ClientVersion> | Visar vilken den senaste släppta klientversionen är. Kan med fördel användas för att kontrollera om det finns någon uppdatering till klientmjukvaran. | version | 1.10 | ||
| <ClientVersionSet> | Visar status i samband med att informationen om klientversionen uppdaterats. | version_update | 1.10 | ||
| <daily> | Har underliggande fält <date>, <average>, <min>, <max> som representerar data för dygn angivet i fältet date. Dessa fält returneras när parametern daily används för att hämta statisk för flera dygn | daily, span, start, end, shift_g | 1.15 | ||
| <ammRange> | Visar för vilket tidsperspektiv amm (medel/min/max) har hämtats | amm, span, start, end, shift_g | 1.11 | ||
| <average> | Medeltemperatur i specificerat tidsperspektiv | amm, span, start, end, shift_g | 1.11 | ||
| <min> | Den minsta temperaturen i specificerat tidsperspektiv | amm, span, start, end, shift_g | 1.11 | ||
| <minTime> | Vid vilken tidpunkt <min> inträffade | amm, span, start, end, shift_g | 1.11 | ||
| <max> | Den högsta temperaturen i specificerat tidsperspektiv | amm, span, start, end, shift_g | 1.11 | ||
| <maxTime> | Vid vilken tidpunkt <max> inträffade | amm, span, start, end, shift_g | 1.11 | ||
| <uptime> | Mätpunktens upptid i % det senaste året | verbose | 1.16 | ||
| <start> | Tidpunkt när mätpunkten lades till på temperatur.nu | verbose | 1.16 | ||
| <moh> | Mätpunktens höjd över havsnivån (Meter above Sea Level) | verbose | 1.16 | ||
| <rawdata> | Temperaturdata i råformat. Varje rawdata-fält innehåller subfälten date, time, timestamp, temperatur | data | 1.16 |
Exempel
Så här kan resultatet från en förfrågan på http://api.temperatur.nu/tnu_1.12.php?p=linkoping&verbose&cli=test_app se ut:
<?xml version='1.0' encoding='iso-8859-1'?>
<rss version="2.0">
<channel>
<title>Temperatur.nu API 1.12 - Din url är inte korrekt signerad, clientnyckeln kan tillfälligt blockeras - /tnu_1.12.php</title>
<link>http://wiki.temperatur.nu/index.php/Api</link>
<item>
<title>Linköping/Centrum</title>
<id>linkoping</id>
<temp>9.3</temp>
<lat>58.414297</lat>
<lon>15.628788</lon>
<lastUpdate>2011-11-24 08:51:25</lastUpdate>
<kommun>Linköping</kommun>
<lan>Östergötlands län</lan>
<sourceInfo>Temperaturdata från Stångå Hotell.</sourceInfo>
<url>http://www.temperatur.nu/linkoping.html</url>
</item>
</channel>
</rss>
Så här kan resultatet från en förfrågan på http://api.temperatur.nu/tnu_1.16.php?lat=58.376761&lon=15.562916&num=3&graph&cli=test_app2 se ut:
<?xml version='1.0' encoding='utf-8'?>
<rss version="2.0">
<channel>
<title>Temperatur.nu API 1.16 - Din url är inte korrekt signerad, clientnyckeln kan tillfälligt blockeras - /tnu_1.16.php</title>
<link>http://wiki.temperatur.nu/index.php/Api</link>
<item>
<title>Linköping/Slaka</title>
<id>slaka</id>
<temp>11.9</temp>
<dist>1.3</dist>
<graph>https://graph.temperatur.nu/graph/slaka-1day-300-200-0-0-0-1-8-n-0-n.png</graph>
</item>
<item>
<title>Linköping/Hagaberg</title>
<id>hagaberg</id>
<temp>12.1</temp>
<dist>3.7</dist>
<graph>https://graph.temperatur.nu/graph/hagaberg-1day-300-200-0-0-0-1-8-n-0-n.png</graph>
</item>
<item>
<title>Linköping/Valla</title>
<id>valla</id>
<temp>11.9</temp>
<dist>3.8</dist>
<graph>https://graph.temperatur.nu/graph/valla-1day-300-200-0-0-0-1-8-n-0-n.png</graph>
</item>
</channel>
</rss>
Signering av URLer
Förfrågningar till APIet kan signeras. Från och med version 1.11 är antalet osignerade förfrågningar begränsade till 20 per timma. Osignerade förfrågningar kommer i framtiden att begränsas för alla api-versioner. Skriver du en privat tillämpning kan du använda APIet utan att signera URLerna.
Signeringen går till så här:
1. Skapa din url som vanligt.
2. Beräkna md5-/sha1-summan av urlen (utan http://) med "+clientnyckel" tillagd på slutet. Klientnyckel erhålls efter att ha mailat [email protected]
3. I slutet av urlen lägger du sedan till &sign=md5-/sha1-summa
I php kan det tex se ut så här om du har en signeringsnyckel för md5:
$cli_key="XXXXXXXXXXXXXXXXXXXXXXXXX"; $url="api.temperatur.nu/tnu_1.9.php?p=linkoping&cli=testapp" $sign=md5($url."+".$cli_key); $signed_url=$url."&sign=".$sign;
I den returnerade xml-filen kan du i det första title-fältet se om förfrågan är korrekt signerad.
fileformat.info är en mycket bra sida för att verifiera att de sha1-/md5-summor du tagit fram stämmer.
Historik/ändringslogg
2010-05-04 - Version 1.0 Första releasen.
2010-05-13 - Version 1.1 Variabeln cli tillagd.
2010-05-19 - Version 1.2 Stöd för att hämta grafer
2010-06-09 - Version 1.3 Bugfix som fixar en bugg introducerad i 1.2 (det gick inte att hämta alla orter genom att skippa variabeln p).
2010-08-04 - Version 1.4 Värden för x och y justerade. Parametern cli krävs för att apiet skall returnera data.
2010-09-01 - Version 1.5 Parametrar för att via mer info i grafen. Parametrar för att visa grafer för i går, förra veckan, 2 år sedan etc.
2010-09-01 - Version 1.6 Parameter för att ange om 1 eller 2 y-axlar skall visas.
2010-11-22 - Version 1.7 Möjlighet att välja hur tjock graflinjen skall vara.
2010-12-19 - Version 1.8 CacheBust-funktion, möjlighet att ändra textstorlek samt information om vem som loggar temperaturen när verbose är specat.
2011-01-13 - Version 1.9 Signeringsfunktion inlagd. Signeringsfunktionen kommer från mitten av 2011 krävas för alla tillämpningar och och kommer successivt att läggas in i alla versioner av apiet.
2011-01-17 - Version 1.10 Möjlighet att via Apiet hantera informaion gällande den senaste tillgängliga klientversionen.
2011-01-30 - Version 1.11 Mer flexibel specificering av tidsperspektiv för grafer. amm - möjlighet att hämta medel/min/max i ett valfritt tidsperspektiv, antalet osignerade accesser begränsat i denna version.
2011-10-08 - Version 1.12 Variabeln history tillagd. Visar föregående periods temperatur i grafer.
2012-05-04 - Version 1.13 Variablerna compare och color angivna, gör det möjligt att jämföra flera orter i samma graf samt helt styra vilka färger linjerna i graferna skall ha. color kan sättas även för vanliga grafer.
2013 - Version 1.14 Parametern history_year som används för att jämföra data med tidigare år. Buggfixar
2014-01-26 - Version 1.15 Parametern daily. Används för att hämta dygnsmedel i ett specificerat tidsspann.
2021-02-25 - Version 1.16 Parametern json för att få ut data i json-format. Parametern data som används för att få ut data i råformat. Mer information returneras när parametern verbose används. Generell buggrättning
