[en|de]

CarbonTracer API

Diese REST-API kann für die Berechnung von Treibausgas (THG) Emissionen (Einheit kgCO2e pro Person) für den Verkehr verwendet werden. Dabei können unterschiedliche Transportmittel aus den Bereichen Straßenverkehr, Schienenverkehr und/oder Flugverkehr angegeben werden .

Inhalte:

Anforderungen

Um diese REST-API verwenden zu können benötigen Sie einen gültigen API-Key. Um einen API-Key zu erhalten, registrieren Sie sich bitte auf dieser Plattform. Die Registrierung sowie die Verwendung der REST-API ist kostenlos. Bitte beachten Sie die Nutzungsbedingungen sowie die Datenschutzbestimmungen.

Sie können maximal 40 Anfragen pro Minute bzw. 2000 Anfragen pro Tag mit einem API-Key durchführen.

Web-API

Die REST-API stellt die Antworten auf Anfragen im JSON-Format bereit.

I. API-Endpunkt

URL
https://api.carbontracer.uni-graz.at/

II. Standort-Anfrage

Endpunkt
/location/{apikey}/{location}
Parameter
{apikey}
string, 40 Zeichen
{location}
String mit vorangestellter Postleitzahl oder nur die Postleitzahl (z.B. Graz, 8010 Graz, 8010 usw)
Es kann zusätzlich der zweistellige ISO-Ländercode am Ende des Strings mitangegeben werden: z.B. Wien, AT; Wien (US), usw
Rückgabe-Wert
{json}
Response-Nachricht

Beispiel (Anfrage ok):
{
 "response": {
  "success": true,
  "warning": false,
  "data": {
   "country": "AT",
   "city": "Graz",
   "postalCode": "",
   "street": "",
   "housenr": "",
   "Longitude": 15.5417,
   "latitute": 47.0833,
   "countryCode": "",
   "label": "Graz, AT"
  }
 }
}


Beispiel (Anfrage Fehler):
{
 "response": {
  "success": false,
  "errors": [
    "Array mit Fehlermeldungen..."
   ]
 }
}


Beispiel (Anfrage Warning):
{
 "response": {
  "success": true,
  "warning": true,
  "warning_message": true,
  "data": {
   "key": [
     "Array mit Vorschlägen"

    ]
  }
 }
}
Beispiel-Anfragen
Beispiele
https://api.carbontracer.uni-graz.at/location/{api-key-hier-einsetzen}/Wien, AT
https://api.carbontracer.uni-graz.at/location/{api-key-hier-einsetzen} /8010
https://api.carbontracer.uni-graz.at/location/{api-key-hier-einsetzen}/8010 Graz

III. Address-Anfrage

Endpunkt
/address/{apikey}/{postalCode}/{city}/{street}
Parameter
{apikey}
string, 40 Zeichen
{postalCode}
nummerischer String (z. B. 8010)
{city}
string (z.B. Graz)
{street}
string mit Straßennamen und Hausnummer (z.B. Carnerigasse 38)
Rückgabe-Wert
{json}
Response-Nachricht

Beispiel (Anfrage ok):
{
 "response": {
  "success": true,
  "warning": false,
  "data": {
   "country": "AT",
   "city": "Graz",
   "postalCode": "8010",
   "street": "Carnerigasse",
   "housenr": "38",
   "Longitude": 15.428546,
   "latitute": 47.087065,
   "countryCode": "AUT",
   "label": "Carnerigasse 38, 8010 Graz, AUT"
  }
 }
}


Beispiel (Anfrage Fehler):
{
 "response": {
  "success": false,
  "errors": [
    "Array mit Fehlermeldungen..."
   ]
 }
}
Beispiel-Anfragen
Beispiele
https://api.carbontracer.uni-graz.at/address/{api-key-hier-einsetzen} /8010/Graz/Carnerigasse 38

IV. Routing Anfrage

Besonderheit bei Verkehrsmittel "car" und "e-car":
Bei diesen Verkehrstmitteln kann zusätzlich die Belegung als Parameter mitgegeben werden (siehe Beispiel-Requests). Wird keine Belegung angegeben, so wird automatisch 1 als Fahrzeugbelegung angenommen.
Endpunkt
/routing/{apikey}/{typ}/{start}/{dest}
/routing/{apikey}/{typ}/{start}/{dest}/options={opts}
Parameter
{apikey}
string, 40 Zeichen
{start}
Start: String mit vorangestellter PLZ
oder Geokoordination (Latitude, Longitude) durch Beistriche getrennt
(z. B. Graz, 8010 Graz, 8010, 47.087065,15.428546 etc)
{dest}
Ziel: String mit vorangestellter PLZ
oder Geokoordination Latitude, Longitude) durch Beistriche getrennt
(z. B. Graz, 8010 Graz, 8010, 47.087065,15.428546 etc)
{opts}
Optionale Parameter: durch Beistrich getrennt
Mögliche Werte: waypoints,bbox,airports
waypoints: liefert die berechneten Wegpunkte für die Anzeige in einer Map zurück.
bbox: liefert die BBOX für die Anzeige in einer Map zurück
airports: für die Flugroutenberechnung: nimmt anstatt des angegeben Standortes den nächsten Flughafen ausgehend vom Standort
{typ}
car (Auto), e-car (E-Auto), bus (Bus), e-bus (E-Bus), flight-firstclass (1. Klasse Flug), flight-business (Business Flug), flight-economy (Flug normal), train (Zug - Sitzplatz), trainL (Zug - Liegewagen), trainS (Zug - Schlafwagen)
Rückgabe-Wert
{json}
Response-Nachricht

Beispiel (Anfrage ok):
{
 "response": {
  "success": true,
  "warning": false,
  "data": {
   "startLocation": {
    "country": "AT",
    "city": "Wien",
    ...
    "label": "1010 Wien, AT"
   },
   "endLocation": {
    "country": "DE",
    "city": "Munchen",
    ...
    "label": "09041 Munchen, DE"
   },
   "distanceDirect": 411.533,
   "distanceRoute": 411.533,
   "co2eq": 8.306,
   "occupancy": 2,
   "co2eq_occupancy": 4.153,
   "unitco2eq": "kg",
   "unitdistance": "km",
   additionalInformation : [
    "String 1"
    "String 2"
   ]
   "time": 0 (experimental),
   "wayPoints": [
    [
     [
     16.375864,
     48.18493
     ],
     [
     16.284941,
     48.173489
     ],
     ....
     [
     11.558342,
     48.140285
     ]
    ]
   ],
 "bbox": [
   12.132507,
   46.120507999999994,
   15.751850999999998,
   47.656039
  ]
   "requestType": "train",
   "aCo2PerCountry": {
    "AT": 4.395,
    "DE": 3.911
   } (für Schienenverkehr)
  }
 }
}


Beispiel (Anfrage Fehler):
{
 "response": {
  "success": false,
  "errors": [
    "Array Liste mit Fehlermeldungen..."
   ]
 }
}


Beispiel (Anfrage Warning):
{
 "response": {
  "success": true,
  "warning": true,
  "warning_message": true,
  "data": {
   "key": [
     "Array mit Vorschlägen"

    ]
  }
 }
}
Beispiel-Anfragen
Beispiele
https://api.carbontracer.uni-graz.at/routing/{api-key-hier-einsetzen} /car/Friesach/Graz
https://api.carbontracer.uni-graz.at/routing/{api-key-hier-einsetzen} /car/Graz/München/options=bbox,waypoints
https://api.carbontracer.uni-graz.at/routing/{api-key-hier-einsetzen} /flight-economy/8010/1010
https://api.carbontracer.uni-graz.at/routing/{api-key-hier-einsetzen} /car/46.782025,15.541402/47.087065,15.428546/options=bbox

V. Andere Anfrage

Endpunkt
/co2only/{apikey}/{typ}/{distance_km}
Parameter
{apikey}
string, 40 Zeichen
{typ}
car (Auto), e-car (E-Auto), bus (Bus), e-bus (E-Bus), flight-firstclass (1. Klasse Flug), flight-business (Business Flug), flight-economy (Flug normal), train (Zug: Sitzplatz), trainL (Zug: Liegewagen), trainS (Zug: Schlafwagen)
{distance_km}
Distanz in Kilometer
Rückgabewert
{json}
Antwort Nachricht

Beispiel (Anfrage OK):
{
 "response": {
  "success": true,
  "warning": false,
s   "data": {
   "distance": 100,
   "co2eq": 6,
   "unitco2eq": "kg",
   "unitdistance": "km",
   "requestType": "train"
  }
 }
}


Beispiel (Anfrage Fehler)
{
 "response": {
  "success": false,
  "errors": [
    "Array-List of error messages..."
   ]
 }
}
Beispiel Requests
Beispiele
https://api.carbontracer.uni-graz.at/co2only/{api-key-hier-einsetzen}/train/50
https://api.carbontracer.uni-graz.at/co2only/{api-key-hier-einsetzen}/car/77
https://api.carbontracer.uni-graz.at/co2only/{api-key-hier-einsetzen}/flight-economy/1332

Excel-API

Diese API stellt die Rückgabewerte als Text-Ergebnis (Plain-Text) bereit und kann so einfach in beispielsweise Excel-Anwendungen eingebunden werden.

I. ExcelAPI-Endpunkt

URL
https://api.carbontracer.uni-graz.at/excel/

II. Standort-Anfrage

Endpunkt
/location/{apikey}/{location}
Parameter
{apikey}
string, 40 Zeichen
{location}
string mit oder ohne vorangestellter Postleitzahl (z. B. Graz, 8010 Graz, 8010 etc)
Rückgabe-Wert
{string}
Standort mit Geokoordinaten (z. B. Graz (47.08540, 15.437888))
oder Fehlermeldung.
Beispiel-Anfragen
Beispiele
https://api.carbontracer.uni-graz.at/excel/location/{api-key-hier-einsetzen} /Graz
https://api.carbontracer.uni-graz.at/excel/location/{api-key-hier-einsetzen} /8010
https://api.carbontracer.uni-graz.at/excel/location/{api-key-hier-einsetzen} /8010 Graz

III. Address-Anfrage

Endpunkt
/address/{apikey}/{postalCode}/{city}/{street}
Parameter
{apikey}
string, 40 Zeichen
{postalCode}
numeric string (z. B. 8010)
{city}
string (z. B. Graz)
{street}
string mit Straßennahmen und Hausnummer (z. B. Carnerigasse 38)
Rückgabe-Wert
{string}
gefundene Adresse mit Geokoordinaten (z. B. Carnerigasse 38, Graz, ST, Austria (47.087065,15.428546))
oder Fehlermeldung
Beispiel-Anfragen
Beispiele
https://api.carbontracer.uni-graz.at/excel/address/{api-key-hier-einsetzen} /8010/Graz/Carnerigasse 38

IV. Routing-Anfrage (CO2eq)

Endpunkt
/routing/co2/{apikey}/{typ}/{start}/{dest}
Parameter
{apikey}
string, 40 Zeichen
{start}
Start: String mit vorangestellter Postleitzahl oder ohne Postleitzahl
oder Geokoordinaten (Latitude, Longitude) durch Beistriche getrennt
(z. B. Graz, 8010 Graz, 8010, 47.087065,15.428546 etc)
{dest}
Ziel: String mit vorangestellter Postleitzahl oder ohne Postleitzahl
oder Geokoordinaten (Latitude, Longitude) durch Beistriche getrennt
(z. B. Graz, 8010 Graz, 8010, 47.087065,15.428546 etc)
{typ}
car (Auto), e-car (E-Auto), bus (Bus), e-bus (E-Bus), flight-firstclass (1. Klasse Flug), flight-business (Business Flug), flight-economy (Flug normal), train (Zug - Sitzplatz), trainL (Zug - Liegewagen), trainS (Zug - Schlafwagen)
Rückgabe-Wert
{double}
CO2 Emissionen in kgCO2eq (z. B. 23.32)
{string}
on error
Beispiel-Anfragen
Beispiele
https://api.carbontracer.uni-graz.at/excel/routing/co2/{api-key-hier-einsetzen} /car/Friesach/Graz
https://api.carbontracer.uni-graz.at/excel/routing/co2/{api-key-hier-einsetzen} /car/Graz/München
https://api.carbontracer.uni-graz.at/excel/routing/co2/{api-key-hier-einsetzen} /flight-economy/8010/1010
https://api.carbontracer.uni-graz.at/excel/routing/co2/{api-key-hier-einsetzen} /car/46.782025,15.541402/47.087065,15.428546

V. Routing-Anfrage (Distanz)

Endpunkt
/routing/distance/{apikey}/{typ}/{start}/{dest}
Parameter
{apikey}
string, 40 Zeichen
{start}
Start: String mit vorangestellter Postleitzahl oder ohne Postleitzahl
oder Geokoordinaten (Latitude, Longitude) durch Beistriche getrennt
(z. B. Graz, 8010 Graz, 8010, 47.087065,15.428546 etc)
{dest}
Ziel: String mit vorangestellter Postleitzahl oder ohne Postleitzahl
oder Geokoordinaten (Latitude, Longitude) durch Beistriche getrennt
(z. B. Graz, 8010 Graz, 8010, 47.087065,15.428546 etc)
{typ}
car (Auto), e-car (E-Auto), bus (Bus), e-bus (E-Bus), flight-firstclass (1. Klasse Flug), flight-business (Business Flug), flight-economy (Flug normal), train (Zug - Sitzplatz), trainL (Zug - Liegewagen), trainS (Zug - Schlafwagen)
Rückgabe-Wert
{double}
Distance in km (z. B. 134.23)
{string}
on error
Beispiel-Anfragen
Beispiele
https://api.carbontracer.uni-graz.at/excel/routing/distance/{api-key-hier-einsetzen} /car/Friesach/Graz
https://api.carbontracer.uni-graz.at/excel/routing/distance/{api-key-hier-einsetzen} /car/Graz/München
https://api.carbontracer.uni-graz.at/excel/routing/distance/{api-key-hier-einsetzen} /flight-economy/8010/1010
https://api.carbontracer.uni-graz.at/excel/routing/distance/{api-key-hier-einsetzen} /car/46.782025,15.541402/47.087065,15.428546

VI. Andere Anfragen

Endpunkt
/excel/co2only/{apikey}/{typ}/{distance_km}
Parameter
{apikey}
string, 40 Zeichen
{typ}
car (Auto), e-car (E-Auto), bus (Bus), e-bus (E-Bus), flight-firstclass (1. Klasse Flug), flight-business (Business Flug), flight-economy (Flug normal), train (Zug: Sitzplatz), trainL (Zug: Liegewagen), trainS (Zug: Schlafwagen)
{distance_km}
Distanz in Kilometer
{double}
CO2 Emissionen in kgCO2eq (e.g. 23.32)
{string}
Fehlermeldung
Beispiel Anfragen
Beispiele
https://api.carbontracer.uni-graz.at/excel/co2only/{api-key-hier-einsetzen}/train/50
https://api.carbontracer.uni-graz.at/excel/co2only/{api-key-hier-einsetzen}/car/77
https://api.carbontracer.uni-graz.at/excel/co2only/{api-key-hier-einsetzen}/flight-economy/1332