CarbonTracer API

This API is used to calculate GHG emissions (unit kgCO2e per person) (kgCO2eq) based on different modes of transport (road, rail, air) and routes. The routes are calculated based on actual road routes, train routes and taking into account various parameters for air traffic.

Contents:

Requirements

To use the API you need a valid API key. You need to register online on this platform to get an API key. The registration and use of this web service is free. Please mind the terms of use and data protection declaration.

You can make a maximum of 40 requests per minute or 2000 requests per day per API key.

Web-API

This API is provided for most applications and projects and returns values in json format.

I. API-Endpoint

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

II. Location Request, Location Validation

Endpoint
/location/{apikey}/{location}
Parameters
{apikey}
string, 40 characters
{location}
string with or without prefixed postal code or only postal code. (e.g. Graz, 8010 Graz, 8010 etc)
you can also add the 2-letter-country-code at the end of the string to search in an specific country: e.g. Wien, AT; Wien (US), etc
Return value
{json}
Response-Message

Success-Example:
{
 "response": {
  "success": true,
  "data": {
   "country": "AT",
   "city": "Graz",
   "postalCode": "",
   "street": "",
   "housenr": "",
   "longitude": 15.5417,
   "latitute": 47.0833,
   "countryCode": "",
   "label": "Graz, AT"
  }
 }
}


Error-Example:
{
 "response": {
  "success": false,
  "errors": [
    "Array-List of error messages..."
   ]
 }
}


Warning-Example:
{
 "response": {
  "success": true,
  "warning": true,
  "warning_message": true,
  "data": {
   "key": [
     "Array with suggestions"

    ]
  }
 }
}
Example requests
Examples
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 Request, Address Validation

Endpoint
/address/{apikey}/{postalCode}/{city}/{street}
Parameters
{apikey}
string, 40 characters
{postalCode}
numeric string (e.g. 8010)
{city}
string (e.g. Graz)
{street}
string with street name and house no. (e.g. Carnerigasse 38)
Return value
{json}
Response-Message

Success-Example:
{
 "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"
  }
 }
}


Error-Example:
{
 "response": {
  "success": false,
  "errors": [
    "Array-List of error messages..."
   ]
 }
}
Example requests
Examples
https://api.carbontracer.uni-graz.at/address/{api-key-hier-einsetzen}/8010/Graz/Carnerigasse 38

IV. Routing Request

Routing-types "car" und "e-car":
You can set an additional parameter "occupancy" (see also example-requests). Occupancy 1 is default if no occupancy is set.
Endpoint
/routing/co2/{apikey}/{typ}/{start}/{dest}
/routing/co2/{apikey}/{typ}/{start}/{dest}/options={opts}
Parameters
{apikey}
string, 40 characters
{start}
Start: string with or without prefixed postal code or only postal code
or Geocoordinates (latitude, longitude) separated by comma
(e.g. Graz, 8010 Graz, 8010, 47.087065,15.428546 etc)
{dest}
Destination: string with or without prefixed postal code or only postal code
or Geocoordinates (latitude, longitude) separated by comma
(e.g. Graz, 8010 Graz, 8010, 47.087065,15.428546 etc)
{opts}
Additional Options: comma separated options
possible values: waypoints,bbox,airports
waypoints: get Waypoints to display route in map
bbox: get bbox for map
airports: in case of flight-routing - take nearest airports of location instead of location
{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)
Return value
{json}
Response-Message

Success-Example:
{
 "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
   } (only for train-calculation)
  }
 }
}


Error-Example:
{
 "response": {
  "success": false,
  "errors": [
    "Array-List of error messages..."
   ]
 }
}


Warning-Example:
{
 "response": {
  "success": true,
  "warning": true,
  "warning_message": true,
  "data": {
   "key": [
     "Array with suggestions"

    ]
  }
 }
}
Example requests
Examples
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. Other Requests

Endpoint
/co2only/{apikey}/{typ}/{distance_km}
Parameters
{apikey}
string, 40 characters
{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}
distance in kilometers
Return value
{json}
Response-Message

Success-Example:
{
 "response": {
  "success": true,
  "warning": false,
  "data": {
   "distance": 100,
   "co2eq": 6,
   "unitco2eq": "kg",
   "unitdistance": "km",
   "requestType": "train"
  }
 }
}


Error-Example:
{
 "response": {
  "success": false,
  "errors": [
    "Array-List of error messages..."
   ]
 }
}
Example requests
Examples
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

This API is provided specifically for use from applications such as MS Excel and returns values in plain text.

I. ExcelAPI-Endpoint

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

II. Location Request, Location Validation

Endpoint
/excel/location/{apikey}/{location}
Parameters
{apikey}
string, 40 characters
{location}
string with or without prefixed postal code or only postal code (e.g. Graz, 8010 Graz, 8010 etc)
Return value
{string}
found location with geocoordinates (e.g. Graz (47.08540, 15.437888))
or error message.
Example requests
Examples
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 Request, Address Validation

Endpoint
/excel/address/{apikey}/{postalCode}/{city}/{street}
Parameters
{apikey}
string, 40 characters
{postalCode}
numeric string (e.g. 8010)
{city}
string (e.g. Graz)
{street}
string with street name and house no. (e.g. Carnerigasse 38)
Return value
{string}
found adrress with geocoordinates (e.g. Carnerigasse 38, Graz, ST, Austria (47.087065,15.428546))
or error msg
Example requests
Examples
https://api.carbontracer.uni-graz.at/excel/address/{api-key-hier-einsetzen}/8010/Graz/Carnerigasse 38

IV. Routing Request (CO2 Emissions)

Endpoint
/excel/routing/co2/{apikey}/{typ}/{start}/{dest}
Parameters
{apikey}
string, 40 characters
{start}
Start: string with or without prefixed postal code or only postal code
or Geocoordinates (latitude, longitude) separated by comma
(e.g. Graz, 8010 Graz, 8010, 47.087065,15.428546 etc)
{dest}
Destination: string with or without prefixed postal code or only postal code
or Geocoordinates (latitude, longitude) separated by comma
(e.g. 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)
Return value
{double}
CO2 emissions in kgCO2eq (e.g. 23.32)
{string}
on error
Example requests
Examples
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 Request (Distance)

Endpoint
/excel/routing/distance/{apikey}/{typ}/{start}/{dest}
Parameters
{apikey}
string, 40 characters
{start}
Start: string with or without prefixed postal code or only postal code
or Geocoordinates (latitude, longitude) separated by comma
(e.g. Graz, 8010 Graz, 8010, 47.087065,15.428546 etc)
{dest}
Destination: string with or without prefixed postal code or only postal code
or Geocoordinates (latitude, longitude) separated by comma
(e.g. 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)
Return value
{double}
Distance in km (e.g. 134.23)
{string}
on error
Example requests
Examples
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. Other Requests

Endpoint
/excel/co2only/{apikey}/{typ}/{distance_km}
Parameters
{apikey}
string, 40 characters
{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}
distance in kilometers
{double}
CO2 emissions in kgCO2eq (e.g. 23.32)
{string}
on error
Example requests
Examples
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