Version HistoryVersion History

Name

REST-APIs

Title

REST APIs

Rollup Image

 

Target Audiences

No targeting

Page Image

 

Page Content

 

A certain number of metrics are now available via REST APIs as listed in the Metrics Catalogue. More APIs to other metric-sets will be developed in the near future. Visualize the metrics on a map using our Map Builder application.

 

If you want to use those metrics in your applications, websites or view it as a spreadsheet, you should purchase an API Key with a sufficient number of tokens from our online store and access the data using the REST interface. Each REST API will depit a certain number of tokens from the API Key at every call as mentioned on the specific REST API documentation.
 
You can also request a trial API KEY (containing 100 tokens, valid 30 days). Trial keys are limited to one per email address. The key will be sent to you by email. You can try out our APIs using the Metrics Catalogue.

 
For more information or questions, do not hesitate to contact us.
 

URL

 
The general URL for the REST APIs is the following:
 

http[s]://istarsapi.net/public/{ressource}.{format}?api_key={YOURKEY}[&entities={countrycode}][&valuesonly={true|false}][&aggregate={true|false}][&history={true|false}]​[&tofile={true|false}][&callback=?]

 
Parameters between square brackets [] are optional. The API can be accessed either via HTTP or HTTPS. The API is case sensitive. The HTTP/HTTPS Content-Type for all responses is set to "text/plain" regardless of the actual format. The callback parameter allows JSONP response, if set.

Parameter ​Explanation
​{ressource} ​The path to the specific REST API as mentioned in the documentation related to the catalogue of APIs
​{format} ​Valid formats are json, csv and html.
entities ​3-letter ISO ALPHA-3 code of the state for which the data is requested; multiple, comma-separated entries are also supported (eg. 'entities=FRA,DEU,BEL'); if the state parameter is omitted, all available States will be returned
api_key ​API key number which will be unique for each user and sent to you on request
​callback ​If set, will return the data wrapped as JSONP. Can be used for cross-domain AJAX calls.
​valuesonly ​The full names of the States are normally part of the API response. If set to true, no names will be provided. Default if ommitted is false
​history If true and if available for the specfic API, historic values for all metrics will be added to the API response together with a date field. Default if ommitted is false
​aggregate ​If true, all metrics will be either summed or averaged (if metric unit is %) over the list of provided states. Only the aggregated values will be returned. Default if ommitted is false.

​For CSV format only ​

​​tofile If set to true, the CSV output will be stored in a file on our server. A single JSON object will be returned containing a CSVFile field with the name of the CSV file.
 

Fields

The fields contained in the API are as mentioned in the documentation for the specific REST API.
In CSV or HTML format, the fields are displayed as columns, the first 2 columns being always the name and the country code of the States.
 
In JSON format, the response structure is always as follows:
{
"name": String(API Name),
"metrics": Array of Strings with metric names,
"entities": Set of State codes with names,
"history" : {true|false},
"aggregation":{true|false},
"values": Set of State codes with array of metric values, ordered as per the "metrics" attribute
}
  

Usage Examples

The API outputs can be viewed in any browser by copying the API URL into the address bar of the browser. Websites or servers can access the API via AJAX calls through jQuery for example.

 

The table below provides a few examples on how the API can be used:

 

​Input/Description/Output

​Example 1 ​

​Input http://istarsapi.net/public/metrics/safety/states/ssc.json?api_key={YOURKEY}&entities=LUX,FRA
Description
Returns the SSC metrics in a JSON format as shown below
Output

{  "name": "ssc",  "metrics": [    "ssc",    "nb_ssc"  ],  "entities": {    "LUX": {      "Name": "Luxembourg"    },    "FRA": {      "Name": "France"    }  },  "history": false,  "values": {    "LUX": [      0,      0    ],    "FRA": [      0,      0    ]  } }

​Example 2 ​

​Input http://istarsapi.net/public/metrics/safety/states/ssc.csv?api_key={YOURKEY}
Description Returns a CSV file containing the metrics fields for all countries in a table format. You can use this API directly in EXCEL to import data using the function Data->From Text (Get External Data) and copying the API address into the "File name" field.
​Output ​text formatted as comma-seperated CSV

​Example 3 ​

​Input http://istarsapi.net/public/metrics/safety/states/ssc.html?api_key={YOURKEY}&entities=LUX,FRA
Description Returns a string formatted as an HTML TABLE element, containing the metrics for France and Luxembourg, one country per row This string can be copied directly into a DOM element on the page and manipulated with jQuery for example.
Output ​text formatted as HTML <table> element
 
 

Resume

AutoTranslation

No

ItemsAutoCreation

None

SharePoint_Group_Language

0

Link Document

 

ICAOLinkDocument2

 

Is RESTAPI

 
Content Type: ICAO Pages
Version: 13.0
Created at 26/06/2013 8:04 AM by Merens, Marco
Last modified at 18/03/2014 12:13 PM by Merens, Marco