VATEUD API

July 28, 2013 at 10:54 AM

VATEUD public API for accessing members data and p[Mod - Happy Thoughts]ing it downstream to vACCs is now available. We also have endpoints for retrieving and scoping online stations data, notams, charts and other goodies. Check out the full description below.

The latest & current API docomeentation can be found at api.vateud.net

Source code at: https://github.com/tarakanbg/api.vateud.net

Features

The API supports json, xml and csv for its data. Use whatever you prefer.
It requires no authentication, no API keys, just send a plain GET request and you're served.
Be reasonable when polling for changes: the data is only updated once a day anyway.
These API calls are served by our EUD server, hence they impose no load or access concerns on the upstream VATSIM databases.
Action caching is used, all responses are cached, expiration time is 3 hours.
Authenticated endpoint for vACCs to obtain the emails of their own members (see below)
Public endpoints for obtaining online stations data (pilots, ATCOs) and scoping it by airport(s)/FIR(s)
Public endpoints for obtaining an always current list of RW NOTAMs scoped by airport(s)/FIR(s)
HTML interface for all public endpoints

The subset of data available includes:

For the members data:

Vatsim ID
First and last name
ATC Rating
Pilot Rating
Humanized ATC Rating
Humanized Pilot Rating
Country
Registration date
Subdivision (vACC)
Email: by using the authenticated vACC specific endpoint (see below)
Suspension end date (if any): by using the authenticated vACC specific endpoint (see below)

Note: The first/last names are preemptively capitalized "on the fly" for you; many aren't in the VATSIM database. Also I'm humanizing the ATC and pilot ratings so you don't have to The original integer values for both ratings are kept in the data for compatibility, should you need them.

For the online stations data:

cid (VATSIM ID)
callsign
name
role
frequency
altitude
planned_altitude (or FL)
heading
groundspeed
transponder
aircraft
origin
destination
route
rating (returns a humanized version of the VATSIM rating: S1, S2, S3, C1, etc...)
facility
remarks
atis (raw atis, as reported from VATSIM, including voice server as first line)
atis_message (a humanized version of the ATC atis w/o server and with lines split)
logon (login time as unp[Mod - Happy Thoughts]d time string: 20120722091954)
online_since (returns the station login time p[Mod - Happy Thoughts]d as a Ruby Time object in UTC)
latitude
longitude
latitude_humanized (e.g. N44.09780)
longitude_humanized (e.g. W58.41483)
qnh_in (indicated QNH in inches Hg)
qnh_mb (indicated QNH in milibars/hectopascals)
flight_type (I for IFR, V for VFR, etc)
gcmap (returns a great circle map image url)

You can either request all EUD members or scope them through a subdivision (vACC) or country or rating.

All records are sorted in reverse chronological order for conveneince (newest on top), but granted you have the reg date in the data you can p[Mod - Happy Thoughts] them any way you want.

Here's how it works:

You have basic url to poll with a GET request and you must append either a json, xml or csv extension to the end of the url to get the relevant format.

Omitting the format extension will return an HTML response: part of the API web interface.

All URL's use the api.vateud.net subdomain, the older vaccs.vateud.net one is kept indefinitely for compatibility and CNAME-d to the main one.

A. Pulling all records

http://api.vateud.net/members.json      #=> returns all EUD members in JSON format
http://api.vateud.net/members.xml      #=> returns all EUD members in XML format
http://api.vateud.net/members.csv      #=> returns all EUD members in CSV format

B. Scoping through vACC

http://api.vateud.net/members/BULG.json     #=> returns all members of the Bulgarian vACC in JSON format
http://api.vateud.net/members/BHZ.xml     #=> returns all members of the Bosnia-Herzegovina vACC in XML format
http://api.vateud.net/members/GRE.csv     #=> returns all members of the Greece vACC in CSV format

As you can see, scoping through vACC is a matter of adding the vACC code designator to the request URL. You can check all vacc codes here.

The vACC codes inside the URL are NOT case sensitive, so you can as well use:

http://api.vateud.net/members/aust.json        #=> returns all members of the Austrian vACC in JSON format
http://api.vateud.net/members/yug.xml         #=> returns all members of the Serbian vACC in XML format
http://api.vateud.net/members/fra.csv          #=> returns all members of the France vACC in CSV format

C. Scoping through country

The vast majority of users do not belong to a subdivision (vACC). Each user though belongs to a country (it's mandatory to select one during initial registration on VATSIM). I thought it might be a useful metrics to provide member listings by country, thus vACC staff should be able to see all VATSIM member from their country and which vACC they belong to (if any).

The base URL you need to poll for this is: vaccs.vateud.net/countries/ and add the country code and format extension:

http://api.vateud.net/countries/BG.json         #=> returns all members from Bulgaria in JSON format
http://api.vateud.net/countries/CH.xml         #=> returns all members from Switzerland in XML format
http://api.vateud.net/countries/BE.csv          #=> returns all members from Belgium in CSV format

You can see all available country codes at api.vateud.net/countries

D. Scoping through rating

You can also scope the members through rating.

The base URL you need to poll for this is: api.vateud.net/ratings/ and add the rating code and format extension:

http://api.vateud.net/ratings/7.json            #=> returns all C3 (Senior Controller) members in JSON format
http://api.vateud.net/ratings/8.xml             #=> returns all INS (Instructor) members in XML format
http://api.vateud.net/ratings/2.csv             #=> returns all S1 (Student) members in CSV format

You can see all available rating codes at api.vateud.net/ratings

E. Authenticated endpoint for vACC email listings

Features

vACCs are able to obtain member listings including their members' emails by using an authenticated endpoint utilizing unique access tokens
Accessing this endpoint without an access token will result in a 401 error
Access tokens are [Mod - Happy Thoughts]ociated with a particular vACC and are only good for that vACC: they can't be used to access the member listings of other vACCs or any other scope of members (error message will be returned). I.e. an access token issued to vACCBUL is only good for fetching vACCBUL members, can't be used for fetching let's say VATITA or vACC Austria members or any members that have selected Bulgaria as a country but do not belong to vACCBUL.
Access tokens will be issued on vACC staff member request, preferably coming from the vACC webmaster or director. You can request an access token for your vACC by creating a task, [Mod - Happy Thoughts]igned to me (or the current VATEUD7) here: tasks.vateud.net
VATEUD reserves the right to revoke an access token and/or replace it if leaks or abuse is detected.

How it works:

The endpoint for this is of the type "api.vateud.net/emails/" + vACC code + desired format extension .

The access token should be p[Mod - Happy Thoughts]ed as a header together with the GET request in the following syntax: 'Authorization: Token token="your-vacc-access-token"'.

I considered including the access token as part of the URL requests, but given the nefarious habit of Internet users to share links left, right and center, decided against it, sorry.

You can use curl or any alternative that you fancy.

Examples:

curl api.vateud.net/emails/bhz.json  -H 'Authorization: Token token="bhz-vacc-access-token"'         #=>  returns the members listing for Bosnia-Herzegovina vACC in json format

curl api.vateud.net/emails/bulg.xml  -H 'Authorization: Token token="bulg-vacc-access-token"'         #=>  returns the members listing for Bulgaria vACC in xml format

curl api.vateud.net/emails/gre.csv  -H 'Authorization: Token token="gre-vacc-access-token"'         #=>  returns the members listing for Greek vACC in csv format

curl api.vateud.net/emails/bhz.json  -H 'Authorization: Token token="non-existing-token"'          #=>  returns 401 unauthorized error

curl api.vateud.net/emails/bhz.json                                                                #=>  returns 401 unauthorized error

curl api.vateud.net/emails/bhz.json  -H 'Authorization: Token token="another-vacc-token"'          #=> returns an eloquent error message

Essentially the data you get via this endpoint is the same data you get via the "members" endpoint. The only difference being that this one also includes the emails.

A note regarding pilot ratings: Pilot ratings are stored as a bitmask in the VATSIM database, and are included the same way in the raw data that we give you. They are additionally "humanized" for convenience (look for the "humanized pilot rating" field). In order to understand what bitmask is and how it works, read this simple explanation. Also you can use Google as bitmask calculator. Here are some example bitmask representations of pilot rating combinations, based on the currently available pilot ratings:

0  => "P0"
1  => "P1"
3  => "P1, P2"
4  => "P3"
5  => "P1, P3"
7  => "P1, P2, P3"
9  => "P1, P4"
11 =>  "P1, P2, P4"
15 =>  "P1, P2, P3, P4"
31 =>  "P1, P2, P3, P4, P5"

....etc....

F. Online stations data

This portion of the API is powered by the vatsim_online library. If you're curious to see in detail how it works and the full array of options it provides, head over to the docomeentation.

These are public endpoints of the type: "http://api.vateud.net/online/" + station type + ICAO filter + format type extension

Available station types: atc, pilots, arrivals, departures.

The ICAO filter is a string of full or partial, one or multiple comma separated ICAO codes (designating FIR(s) or airport(s)) that will be used to filter out the requested online data. They are not case sensitive. For example you can use the "ed" filter to show all stations in Germany, or "loww,lowi" filter to show all stations for Vienna and Innsbruck airports, or "low, ed" filter to show all stations for all Austrian and German airports, etc

Examples:

http://api.vateud.net/online/atc/ed.json         #=> returns all German online ATC stations in JSON format
http://api.vateud.net/online/pilots/low.xml      #=> returns all online pilot stations, inbound or outbound to one of Austria's major airports in XML format
http://api.vateud.net/online/arrivals/egll,egcc.csv   #=> returns all inbound flights to London Heathrow or Manchester airports in CSV format
http://api.vateud.net/online/departures/lp.xml     #=> returns all departures from Portuguese airports in xml format

....etc.....

Note: The online stations responses are all being cached with expiration time set to 5 minutes. The online stations data is not limited to EUD, you can use it for any airport(s)/FIR(s) in the world.

G. Current RW NOTAMs

This portion of the API is powered by the notams library. If you're curious to see in detail how it works and the full array of options it provides, head over to the docomeentation.

These are public endpoints of the type: "http://api.vateud.net/notams/" + ICAO filter + format type extension

The ICAO filter is a string of one or multiple comma separated ICAO codes (designating FIR(s) or airport(s)) that will be used to filter out the requested notams data. They are not case sensitive. For example you can use "lqsa,lqmo" to get all notams for Sarajevo and Mostar airports or "lqsb" to get all notams related to Bosnia-Herzegovina FIR, or "LQSA,LQMO,LQSB" to get a combined list of the 2 airports NOTAMs plus all FIR-wide NOTAMs.

The responses will return 3 attributes for each NOTAM:

ICAO - the code of the airport or FIR the NOTAM applies to
raw - the raw record of the notam, providing its full unp[Mod - Happy Thoughts]d content
message - just the essential informational part of the notam, with all the overhead stripped out

All NOTAMs responses are cached, expiration time is currently set at 24 hours.

Examples:

http://api.vateud.net/notams/lqsa.json                 #=> returns all Sarajevo NOTAMs in JSON format  
http://api.vateud.net/notams/LQSA,LQMO,LQSB.xml     #=> returns all NOTAMs for Sarajevo and Mostar airports and BiH FIR in XML format
http://api.vateud.net/notams/loww.csv                  #=> returns all NOTAMs for Vienna Airport in CSV

H. Airport Charts

These are public endpoints of the type: "http://api.vateud.net/charts/" + airport ICAO code + format type extension

Omitting the format type extension will return an html response with a chart listing (part of the API web interface)

The response will return 4 attributes for each chart:

ICAO - the code of the airport the chart refers to
name - the name of the chart
url_aip - link to the official source of the chart
url_charts_aero - link to the cached version of the chart at charts.aero

All chart responses are cached, the expiration time is currently set at 2 hours.

Examples:

   http://api.vateud.net/charts/lowi.json              #=> returns all Innsbruck charts in JSON format  
   http://api.vateud.net/charts/EGLC.xml               #=> returns all London City charts in XML format
   http://api.vateud.net/charts/lgav.csv               #=> returns all Athens airport charts in CSV
   http://api.vateud.net/charts/loww                   #=> returns an HTML listing of all Vienna charts

The chart listings are automatically synchronized with RW sources and are always current. Note, we only provide links to the publications, not physical files.

Not to be used for real world navigation!

So, no more excuses for outdated charts anywhere on vACC / event websites

I. Member Validation

This endpoint is of the type: "http://api.vateud.net/members/validate/".

It receives a member cid and email (sent along a GET request as headers) and matches them against the DB.

It returns `true` if a matching cid/email pair is found or otherwise returns `false`.

Useful for vACCs that run user registration checks on their websites to avoid bot registrations and (to a certain extent) impersonation.

Examples:

    
   # Curl command line:

   curl api.vateud.net/members/validate -H 'cid: 1175035' -H 'email: [email protected]'  #=> true
   curl api.vateud.net/members/validate -H 'cid: 1175036' -H 'email: [email protected]'  #=> false

   # An example Ruby method

   def validate_member(cid, email)
     response = Curl::Easy.http_get("api.vateud.net/members/validate") do |curl|
       curl.headers['cid'] = cid
       curl.headers['email'] = email
     end    
   end

J. Single member details

This endpoint is of the type: `http://api.vateud.net/members/id/` + `vatsim cid` + format type extension.

Omitting the format type extension will return an html response with the member details (part of the API web interface)

The data and logic is exactly the same as with other "members" endpoints with the only difference that this one only returns the details of a single member, identified by their vatsim CID.

This endpoint allows optionally sending a vACC access token as a header in the following syntax:

'Authorization: Token token="your-vacc-access-token"'.

If a valid access token is received, the member details returned will be augmented with 2 extra attributes: member email address and suspension expiration date (if any). This extra data will only be included if the submitted vacc token matches the affeccted member vacc.

If no access token is sent or the access token is invalid or the access token does not match the queried member vacc, then the standart set of public details will be returned, not including the email, etc.

Examples:

   http://api.vateud.net/members/id/1264903.json    #=> returns member's details in JSON format  
   http://api.vateud.net/members/id/1092003.xml     #=> returns member's details in XML format  
   http://api.vateud.net/members/id/973575.csv      #=> returns member's details in CSV format  
   http://api.vateud.net/members/id/890112          #=> returns member's details as HTML  

   curl api.vateud.net/members/id/890112.json -H 'Authorization: Token token="valid-access-token"'
                       #=> returns augmented set of member's details (including email) in json format
   curl api.vateud.net/members/id/890112.xml -H 'Authorization: Token token="valid-access-token"'
                       #=> returns augmented set of member's details (including email) in xml format

   curl api.vateud.net/members/id/890112.json -H 'Authorization: Token token="invalid-access-token"'
               #=> returns standart public set of member's details (not including email) in json format
   curl api.vateud.net/members/id/890112.csv -H 'Authorization: Token token="invalid-access-token"'
                       #=> returns standart set of member's details (not including email) in csv format

K. Online stations data by callsign

This portion of the API is powered by the vatsim_online library. If you're curious to see in detail how it works and the full array of options it provides, head over to the docomeentation.

These are public endpoints of the type:

"http://api.vateud.net/online/callsign/" + callsign filter + format type extension

The callsigns can designate both pilot and ATC stations.

The callsign filter is a string of full or partial, one or multiple comma separated callsigns that will be used to filter out the requested online data. They are not case sensitive. For example you can use the "baw" filter to show all British Airways flights, or "loww,aua" filter to show all atc stations for Vienna airport and all Austrian Airlines flights, or "ach, afr" filter to show all Air Child and Air France flights, etc

Examples:

http://api.vateud.net/online/callsign/baw.json        #=> returns all British Airways flights in JSON format  
http://api.vateud.net/online/callsign/afr.xml         #=> returns all Air France flights in XML format  
http://api.vateud.net/online/callsign/aua,LOWW.csv    #=> returns all Austrian Airlines flights and all
                                                         Vienna airport stations in CSV format  
http://api.vateud.net/online/callsign/ach             #=> returns all Air Child flights as HTML (part of the API web interface)

....etc.....

Note: The online stations responses are all being cached with expiration time set to 5 minutes. The online stations data is not limited to EUD, you can use it for any stations on the network.

L. Events management (calendar)

The VATEUD events management and calendar API is designed to solve the issue of having multiple standalone (isolated) calendar solutions for each vACC and for VATEUD separately and to overcome the limitations of the existing EUD calendar, which is a self contained "silo" with web interface only, and no ways of programmatically reading, creating or updating event data. The new system provides event organizers across EUD with a single point of posting and updating their event announcements following the principle of "publish once (or edit once), display anywhere". This also ensures that all pilots will have the same, full event information wherever they look.

The events management API provides the following abilities:

1. Create, edit, delete events

- a) Via web interface

- b) Programmatically, via authenticated REST-ful API calls

2. Retrieve and scope events

- in 4 different formats JSON, XML, CSV and ICS/iCAL for integration with calendar tools/apps

- scoped either globally (all VATEUD events) or per vACC (each vACCs events listing)

These abilities ensure the following use cases are satisfied:

vACCs don't have to maintain their own calendar systems, they can pull their vACC events from the EUD API in any convenient format and just visualize them on their websites.
vACCs that maintain their own calendar systems can easily synchronize their data with the EUD calendar when creating or updating an event on their end by simultaneously sending calls to the EUD API
Any 3rd party service can use the events API to list VATEUD events. This is how, for example, the new VATEUD website will be getting its event data
The choice between using web backend for events management or using the RESTful API gives both technical and non-technical users/vaccs the opportunity to utilize the system without being inconvenienced

Reading (retrieving) event data

For retrieving the unscoped VATEUD events data (for all vaccs), use the following endpoint:

`http://api.vateud.net/events + format type extension`

Examples:

   http://api.vateud.net/events.json    #=> returns all EUD events in JSON format
   http://api.vateud.net/events.xml     #=> returns all EUD events in XML format
   http://api.vateud.net/events.csv     #=> returns all EUD events in CSV format
   http://api.vateud.net/events.ics     #=> returns all EUD events in ICS format
   http://api.vateud.net/events         #=> returns all EUD events as HTML listing (part of the API web frontend)

For retrieving the Events data scoped by vACC (events by a particular vacc only), use the following endpoint:

`http://api.vateud.net/events/vacc/vacc_code + format type extension`

The list of vACC codes is available at http://api.vateud.net/subdivisions

Examples:

 
  http://api.vateud.net/events/vacc/BHZ.json   #=> returns all Bosnia & Herzegovina events in JSON format
   http://api.vateud.net/events/vacc/AUST.xml   #=> returns all Austria events in XML format
   http://api.vateud.net/events/vacc/GER.csv    #=> returns all Germany events in CSV format
   http://api.vateud.net/events/vacc/GRЕ.ics    #=> returns all Greek events in ICS format
   http://api.vateud.net/events/vacc/BHZ        #=> returns all Bosnia & Herzegovina events as HTML (part of the API web frontend)

For retrieving the details of an individual event, use the following endpoint:

`http://api.vateud.net/events/event_id + format type extension`

Examples:

   http://api.vateud.net/events/4.json  #=> returns the details with event with id 4 in JSON format
   http://api.vateud.net/events/1.xml   #=> returns the details with event with id 1 in XML format
   http://api.vateud.net/events/2.csv   #=> returns the details with event with id 2 in CSV format
   http://api.vateud.net/events/3.ics   #=> returns the details with event with id 3 in ICS format
   http://api.vateud.net/events/1       #=> returns the details with event with id 1 as HTML (part of the API web frontend)

Creating, editing and deleting events programmatically

In order to use the RESTful API CRUD (create, edit and delete endpoints) you'll need an API access token for your vACC. These 3 endpoints only accept authenticated calls. Read above on how to request an API token.

Event record attributes

Each event record can accept the following attributes:

`title` - the event name
`subtitle` - snappy short event summary, i.e. "ICAO fully staffed"
`airports` - a comma separated list of the event airports (ICAO codes)
`description` - the event description. No length limit, can contain HTML
`banner_url` - a link to your banner image, if any
`starts` - starting date and time for the event (zulu) in the following format: "2013-10-27T20:00:00Z". The T letter denotes the beginning of the time string, separating the date and time.
`ends` - ending date and time for the event (zulu) in the following format: "2013-10-27T20:00:00Z". The T letter denotes the beginning of the time string, separating the date and time.
`vaccs` - the vACCs (one or many) that are organizing the event. Determined programmatically by the access token, not editable via remote calls
`id` - unique numeric identifier, returned by the application on create and update calls, not editable

RESTful principle explained

The VATEUD API follows the RESTful convention, meaning you send remote calls to a certain endpoint (optionally including an id), plus you also send in JSON data for the record that you want published/changed and you also authenticate yourself on behalf of a vACC with an API token. The type of HTTP request that you're sending in determines the type of action that you want in the following way:

GET requests are for reading records
POST requests are for creating records
PUT requests are for updating records
DELETE requests are for destroying records

Creating an event record

In order to create an event, you send an HTTP POST request to `http://api.vateud.net/events` with the JSON details of the new event and with your API token (sent as a HEADER along with the request)

Example:

curl -X POST -H "Content-Type: application/json" -d '{"airports":"LBSF,LQSA","banner_url":"http://domain.net/image.jpg",
     "description":"example description, can contain HTML","ends":"2013-10-27T22:00:00Z","starts":"2013-10-27T20:00:00Z",
     "subtitle":"event subtitle","title":"Our Grand Event"}' http://api.vateud.net/events -H 'Authorization: Token token="your-vacc-authorization-token"'

Notes:

The example is a command line CURL call in a UNIX-based OS. The exact syntax will vary depending on the http client implementation and the language you're using. Refer to your http client's docomeentation for full reference.
The order of attributes in the JSON string is irrelevant. In the above example they're ordered alphabetically, but you can do as you please, just remember to wrap both the attribute name and the attribute value in quotes, use colon between the name (label) and the value, and separate the pairs with commas
In the example I have added a header specifying the MIME type of the data that I'm sending: in our case application/json. Strictly speaking this is not necessary. The application expects json and will recognize and accept it even without Content-Type header. Nevertheless it's a general good practice to declare the content type when sending data across, so better do it for consistency.
Note: the Authentication token is sent along as a HEADER!
If the call has been successful and the record is created, the endpoint will return the new record as JSON, including all attributes PLUS the newly created record ID. You probably want to catch and store the ID if you want to be able to programmatically edit or delete this record in the future.
The new event will be tagged and [Mod - Happy Thoughts]igned to the vACC that corresponds to the authentication token used
No record will be created without an authentication token

Editing (updating) an event record

In order to edit (update) an event, you send an HTTP PUT request to `http://api.vateud.net/events/event_id` with the JSON details

that you want changed and with your API token (sent as a HEADER along with the request). Note you need to p[Mod - Happy Thoughts] the event ID to the URL

Example:

curl -X PUT -H "Content-Type: application/json" -d '{"subtitle":"New subtitle","title":"New title"}'
      http://api.vateud.net/events/1 -H 'Authorization: Token token="your-vacc-access-token"'

Notes:

You only need to p[Mod - Happy Thoughts] the attributes that you want changed, not all attributes. The order is irrelevant.
In the example above, the record changed has an ID of 1
The Authentication token is sent along as a HEADER!
If the call has been successful and the record is updated, the endpoint will return the full record as JSON, including all attributes plus the id.
The record will not be updated (error message returned) without an authentication token
The record will not be updated (error message returned) if the authentication token's vACC doesn't match the event record vACC

Deleting an event record

In order to delete an event, you send an HTTP DELETE request to `http://api.vateud.net/events/event_id` with your API token (sent as a HEADER along with the request). Note you need to p[Mod - Happy Thoughts] the event ID to the URL, but you don't need to send any JSON data at this time

Example:

    curl -X DELETE http://localhost:3000/events/3 -H 'Authorization: Token token="your-vacc-access-token"'

Notes:

In the example above, the record changed has an ID of 3
The Authentication token is sent along as a HEADER!
The record will not be deleted (error message returned) without an authentication token
The record will not be deleted (error message returned) if the authentication token's vACC doesn't match the event record vACC

Creating, editing and deleting events via the web backend interface

The backend administrative interface for the VATEUD API is accessible via http://api.vateud.net/admin.

There's also a link called "Staff Zone" in the menu pointing that way.

The backend requires registration, which is open to all users.

The backend functionality available to individual users is dependant on the user's roles. Initially all users start with no roles and they have access to no functionality. When logged in they see a blank dashboard. So don't panick, when you initially register, log in and see nothing useful A user needs to be [Mod - Happy Thoughts]igned one or multiple roles by an admin in order to get backend functionality and menus accessible.

The currently available roles are:

`admin` - unrestricted access
`events` - access to events management
`staff` - access to vACC details and staff lists management (pending future update)

Admins are notified by email when a new user signs up, and after checking their credentials, they'll [Mod - Happy Thoughts]ign him roles, usually within the day.

We will only enable accounts created by vACC staff members.

Users with an "Events" role will see an interface similar to the one below:

Link to image

Search and export functionality is available for convenience.

The Add and Edit forms look like this and are self explanatory (the description field supports rich text formatting and comes with a WYSIWYG editor):

Link to image

The following restrictions apply when manipulating event records via the web backend:

a user can only edit an event if the event's vACC matches the user vacc
a user can only delete an event if the event's vACC matches the user vacc

M. vACC profiles

These endpoints allow fetching the general vACC data, either globally (all EUD subdivisions) or indivisually per vACC. Through the API vACC data can be distributed and visualized on any 3rd party website, including the new EUD website.

The following attrbiutes are exposed for each vACC:

`code` - unique identifying subdivision code, as defined in VATSIM database
`name` - the vACC name
`website` - the vACC website URL
`introtext` - introductory description of the vACC
`official` - boolean flag, marks the vACC as official or unofficial

Editing vACC records

With the introduction of this portion of the API, vACC records transition from EUD-managed to self-managed. Each vACC has the ability to edit their own records without being dependant on EUD staff.

vACC staff members with API accounts and sufficient levels of permission can edit their vACC profiles via the backend web interface of the API.

The web interface for editing vACC records is self explanatory and similar to the pictured below:

Link to image

Notes:

vACC staff members can only edit the record for the vACC they belong to
All changes are logged, tracked and reversible to prevent abuse or accidental data loss
Deleting or creating subdivision is, of course, not possible via the interface
One or more countries can be [Mod - Happy Thoughts]igned ([Mod - Happy Thoughts]ociated) with a particular vACC
The introtext supports HTML and the interface comes with a WYSIWYG editor for that field

Reading vACC records

Fetching all vACC records

This is a public endpoint of the type: `http://api.vateud.net/subdivisions` + `format type extension`

Examples:

   http://api.vateud.net/subdivisions.json   #=> returns all vACCs data in JSON format
   http://api.vateud.net/subdivisions.xml    #=> returns all vACCs data in XML format
   http://api.vateud.net/subdivisions.csv    #=> returns all vACCs data in CSV format
   http://api.vateud.net/subdivisions        #=> returns all vACCs data as HTML (part of the API web interface)

Fetching individual vACC data

These are public endpoints of the type: `http://api.vateud.net/subdivisions/` + `vacc code` + `format type extension`

The full list of vACC codes can be found at http://api.vateud.net/subdivisions

Examples:

 
   http://api.vateud.net/subdivisions/BLUX.json  => returns vACC BeLux details in JSON format
   http://api.vateud.net/subdivisions/ITA.xml    => returns vACC Italy details in XML format
   http://api.vateud.net/subdivisions/SLOV.csv   => returns vACC Slovenia details in CSV format
   http://api.vateud.net/subdivisions/BHZ        => returns vACC B&H details as HTML (part of the API web interface)

N. Self managed vACC Staff Members listings

The VATEUD vACC Staff Members API is designed to enable vACC staff to self-manage and maintain their vACC staff records, via web interface or programmatically, following the principle of "publish once (or edit once), display anywhere". It has built-in mechanisms of tracking and confirming staff changes by EUD staff to avoid abuse or accidental data loss.

The vACC Staff members API provides the following abilities:

1. Create, edit, delete staff members

- a) Via web interface

- b) Programmatically, via authenticated REST-ful API calls

2. Retrieve and scope staff members

- in 3 different formats: JSON, XML, CSV

- scoped either globally (all vACC staff members) or per vACC (each vACCs staff listing)

- ability to retrieve the details of an individual vACC staff position

Any 3rd party service can use the staff members API to list vACC staff. This is how, for example, the new VATEUD website will be getting its staff data, and it can be easily implemented on individual vACC sites as well.

The choice between using web backend for staff management or using the RESTful API gives both technical and non-technical users/vaccs the opportunity to utilize the system without being inconvenienced.

Reading (retrieving) staff members data

For retrieving the unscoped VATEUD staff members data (for all vaccs), use the following endpoint:

`http://api.vateud.net/staff_members` + `format type extension`

**Examples:**

   http://api.vateud.net/staff_members.json    #=> returns all EUD staff members in JSON format
   http://api.vateud.net/staff_members.xml     #=> returns all EUD staff members in XML format
   http://api.vateud.net/staff_members.csv     #=> returns all EUD staff members in CSV format
   http://api.vateud.net/staff_members         #=> returns all EUD staff members as HTML listing (part of the API web frontend)

For retrieving the staff members data scoped by vACC (staff listings for a particular vacc only), use the following endpoint:

`http://api.vateud.net/staff_members/vacc/` + `vacc_code` + `format type extension`

The list of vACC codes is available at http://api.vateud.net/subdivisions

**Examples:**

 
   http://api.vateud.net/staff_members/vacc/BHZ.json   #=> returns all Bosnia & Herzegovina staff members in JSON format
   http://api.vateud.net/staff_members/vacc/AUST.xml   #=> returns all Austria staff members in XML format
   http://api.vateud.net/staff_members/vacc/GER.csv    #=> returns all Germany staff members in CSV format
   http://api.vateud.net/staff_members/vacc/BHZ        #=> returns all Bosnia & Herzegovina staff members as HTML (part of the API web frontend)

For retrieving the details of an individual staff position, use the following endpoint:

`http://api.vateud.net/staff_members/` + `staff member id` + `format type extension`

**Examples:**

   http://api.vateud.net/staff_members/212.json  #=> returns the details for staff member with id 212 in JSON format
   http://api.vateud.net/staff_members/191.xml   #=> returns the details for staff member with id 191 in XML format
   http://api.vateud.net/staff_members/185.csv   #=> returns the details for staff member with id 185 in CSV format
   http://api.vateud.net/staff_members/159       #=> returns the details for staff member with id 159 as HTML (part of the API web frontend)

Creating, editing and deleting staff members programmatically

In order to use the RESTful API CRUD (create, edit and delete endpoints) you'll need an API access token for your vACC.

These 3 endpoints only accept authenticated calls. Read above on how to request an API token.

Staff member attributes

Each staff member record can accept the following attributes:

`callsign` - the staff position callsign, i.e. "ACCSLACK5"
`position` - the position description, i.e. "Leisure Manager"
`cid` - the Vatsim ID of the person occupying the position. Can be blank for vacant positions
`email` - the staff position email. Can be blank for vacant positions
`priority` - mandatory integer (number) attribute, designates the relative order of the posiotion in regards to other positions within the same vACC. I.e. position with priority 1 will be listed abover position with priority 2.
`vacc_code` - the vACC code of the staff member. Determined programmatically by the access token, not editable via remote calls
`id` - unique numeric record identifier, returned by the application on create and update calls, not editable

RESTful principle explained (again)

The VATEUD API follows the RESTful convention, meaning you send remote calls to a certain endpoint (optionally including an id), plus you also send in JSON data for the record that you want published/changed and you also authenticate yourself on behalf of a vACC with an API token. The __type of HTTP request__ that you're sending in determines the type of action that you want in the following way:

GET requests are for __reading__ records
POST requests are for __creating__ records
PUT requests are for __updating__ records
DELETE requests are for __destroying__ records

Creating a staff member record

In order to create an staff member, you send an HTTP __POST request__ to `http://api.vateud.net/staff_members` with the JSON details

of the new position and with your API token (sent as a HEADER along with the request)

Example:

    curl -X POST -H "Content-Type: application/json" -d '{"callsign":"ACCBIH8","position":"New Test Position",
       "cid":"12345678","email":"[email protected]","priority":"8"}' http://api.vateud.net/staff_members 
        -H 'Authorization: Token token="your-vacc-access-token"'

Notes:

The example is a command line CURL call in a UNIX-based OS. The exact syntax will vary depending on the http client implementation and the language you're using. Refer to your http client's docomeentation for full reference.
The order of attributes in the JSON string is irrelevant, just remember to wrap both the attribute name and the attribute value in quotes, use colon between the name (label) and the value, and separate the pairs with commas
In the example I have added a header specifying the MIME type of the data that I'm sending: in our case application/json. Strictly speaking this is not necessary. The application expects json and will recognize and accept it even without Content-Type header. Nevertheless it's a general good practice to declare the content type when sending data across, so better do it for consistency.
Note: the Authentication token is sent along as a HEADER!
If the call has been successful and the record is created, the endpoint will return the new record as JSON, including all attributes PLUS the newly created record ID. You probably want to catch and store the ID if you want to be able to programmatically edit or delete this record in the future.
The new staff member position will be tagged and [Mod - Happy Thoughts]igned to the vACC that corresponds to the authentication token used
No record will be created without an authentication token

Editing (updating) a staff member record

In order to edit (update) a staff member, you send an HTTP __PUT request__ to `http://api.vateud.net/staff_members/staff_member_id` with the JSON details that you want changed and with your API token (sent as a HEADER along with the request). Note you need to p[Mod - Happy Thoughts] the

staff member ID to the URL

Example:

 
  curl -X PUT -H "Content-Type: application/json" -d '{"cid":"12345788","email":"[email protected]"}'
      http://api.vateud.net/staff_members/474 -H 'Authorization: Token token="your_vacc_access_token"'

Notes:

You only need to p[Mod - Happy Thoughts] the attributes that you want changed, not all attributes. The order is irrelevant.
In the example above, the record changed has an ID of 474
The Authentication token is sent along as a HEADER!
If the call has been successful and the record is updated, the endpoint will return the full record as JSON, including all attributes plus the id.
The record will not be updated (error message returned) without an authentication token
The record will not be updated (error message returned) if the authentication token's vACC doesn't match the staff member record vACC

Deleting a staff member record

In order to delete a staff member record, you send an HTTP __DELETE request__ to `http://api.vateud.net/staff_members/staff_member_id` with your API token (sent as a HEADER along with the request). Note you need to p[Mod - Happy Thoughts] the event ID to the URL, but you don't need to send any JSON data at this time

Example:

   curl -X DELETE http://api.vateud.net/staff_members/471 -H 'Authorization: Token token="your_vacc_access_token"'

Notes:

In the example above, the record deleted has an ID of 471
The Authentication token is sent along as a HEADER!
The record will not be deleted (error message returned) without an authentication token
The record will not be deleted (error message returned) if the authentication token's vACC doesn't match the staff member record vACC

Creating, editing and deleting staff members via the web backend interface

The backend administrative interface for the VATEUD API is accessible via http://api.vateud.net/admin.

There's also a link called "Staff Zone" in the menu pointing that way.

The backend requires registration, which is open to all users.

The backend functionality available to individual users is dependant on the user's roles. Initially all users start with no roles and they have access to no functionality. When logged in they see a blank dashboard. So don't panick, when you initially register, log in and see nothing useful A user needs to be [Mod - Happy Thoughts]igned one or multiple roles by an admin in order to get backend functionality and menus accessible.

The currently available roles are:

`admin` - unrestricted access
`events` - access to events management
`staff` - access to vACC details and staff lists management

Admins are notified by email when a new user signs up, and after checking their credentials, they'll [Mod - Happy Thoughts]ign him roles, usually within the day.

We will only enable accounts created by vACC staff members.

Users with a "Staff" role will see an interface similar to the one below:

Link to image

Search and export functionality is available for convenience.

The Add and Edit forms look like this and are self explanatory:

Link to image

The following restrictions apply when manipulating event records via the web backend:

A user can only edit an staff member if the staff member's vACC matches the user vacc
A user can only delete an staff member if the staff member's vACC matches the user vacc
All changes are logged, tracked and reversible to prevent abuse or accidental data loss
A `vateud_confirmed` flag is attached to each record. The flag is set to "false" by default and also reset from "true" to "false" whenever an existing staff member is edited, either via the web interface or programmatically. Only EUD staff with admin level of access to the API can "confirm" staff member records, thus setting the flag to "true". This is to avoid errors and potential abuse, and to make sure EUD staff has an easy way to monitor vACC staff changes as they happen. This flag is for internal reference of EUD staff only and has no impact of the record's availability.

O. Airport profiles

The airports API allows vACC to showcase some or all airports in their respective countries, and make the information available to any 3rd party web service that wants to use it, including event websites, individual vACC websites and the VATEUD website.

Creating airport records is only possible to the API backend for now. vACC staff members with API backend access can create, edit and destroy airport profiles.

Only part of the airport data is filled in and maintained by vACCs, and even a smaller subset of this data is mandatory. The majority of the data listed and available for each airport is obtained and updated programmatically via the airdata library. If you're interested in the technical details, read the docomeentation.

The following attributes are included for each airport:

vACC provided:

`icao` - mandatory, unique. The airport's ICAO identifier.
`iata` - mandatory. The airport's IATA code
`country` - mandatory. The airport's country, chosen from a list of EUD countries
`major` - a boolean field. Designates an airport as being a "major" one
`scenery_fs9_link` - link to FS9 scenery
`scenery_fsx_link` - link to FSX/P3D scenery
`scenery_xp_link` - link to X-Plane scenery
`description` - freetext description of the airport. Supports rich text format and the field comes with a WYSIWYG editor on the backend

Automatically obtained:

`name` - the airport's (or city) name
`elevation` - the airport's elevation in feet
`ta` - the airport's transition altitude
`msa` - the airport's minimum safe altitude
`lat` - the airport's latitude
`lon` - the airport's longitutde

Airport runways (automatically obtained)

`number` - the runway number (designator)
`course` - the runway course
`length` - the runway length in feet
`elevation` - the runway threshold elevation
`lat` - the latitude of the runway threshold
`lon` - the longitude of the runway threshold
`ils` - boolean; true if the runway is equipped with ILS
`ils_fac` - the ILS final aproach course
`ils_freq` - the ILS frequency
`glidepath` - the ILS glidepath angle. Defaults to 3 degrees for runways without ILS

Data structure and format differences

As you can see, it's a big set of data, and it's nested/structured in the API responses, so that all the primary vacc provided attributes are directly listed in the airport set, all the automatically obtained general details are grouped in a "data" subset, and all runways informtion is grouped in a "runways" subset which is nested below "data". The country data is isolated in a separate "country" subset, giving the country code and country name attributes.

Hence an exaple JSON repsonse will look like this:

    {"description":"<p><strong>Sarajevo International Airport</strong> description</p>\r\n",
   "iata":"SJJ","icao":"LQSA","major":true,"scenery_fs9_link":"http://vaccbih.info/downloads",
   "scenery_fsx_link":"http://vaccbih.info/downloads","scenery_xp_link":"http://vaccbih.info/downloads",
   "country":{"code":"BA","name":"Bosnia-Herzegovina"},"data":{"elevation":1708,"icao":"LQSA",
   "lat":43.824472,"lon":18.331767,"msa":8500,"name":"SARAJEVO","ta":9500,"runways":[{"course":115,
   "elevation":1643,"glidepath":3.2,"ils":true,"ils_fac":115,"ils_freq":110.7,"lat":43.829542000000004,
   "length":8530,"lon":18.318231,"number":"12"},{"course":295,"elevation":1690,"glidepath":3.0,"ils":false,
   "ils_fac":0,"ils_freq":0.0,"lat":43.821272,"length":8530,"lon":18.340303,"number":"30"}]}}

XML responses are structured in the same way. CSV responses are "flattened" to include all the general details. Due to the inability of the CSV format to store a subset of arbitrary size, runways information is not included in the CSV responses.

Fetching all EUD airports

These are endpoints of the type: `http://api.vateud.net/airports` + `format type extension`

Examples:

   http://api.vateud.net/airports.json   #=> returns all EUD airports in JSON format
   http://api.vateud.net/airports.xml    #=> returns all EUD airports in XML format
   http://api.vateud.net/airports.csv    #=> returns all EUD airports in CSV format
   http://api.vateud.net/airports        #=> returns all EUD airports as HTML (part of the API web interface)

Scoping the airports per country

These are endpoints of the type: `http://api.vateud.net/airports/country/` + `country code` + `format type extension`

The full list of EUD country codes can be seen at http://api.vateud.net/airports

Examples:

 
  http://api.vateud.net/airports/country/BA.json  #=> returns all Bosnia & Herzegovina airports in JSON format
   http://api.vateud.net/airports/country/BA.xml   #=> returns all Bosnia & Herzegovina airports in XML format
   http://api.vateud.net/airports/country/BA.csv   #=> returns all Bosnia & Herzegovina airports in CSV format
   http://api.vateud.net/airports/country/BA       #=> returns all Bosnia & Herzegovina airports as HTML (part of the API web interface)

Getting individual airport details

These are endpoints of the type: `http://api.vateud.net/airports/` + `ICAO code` + `format type extension`

Examples:

 
   http://api.vateud.net/airports/LQSA.json   => returns the details for Sarajevo airport in JSON format
   http://api.vateud.net/airports/LQMO.xml    => returns the details for Mostar airport in XML format
   http://api.vateud.net/airports/LQTZ.csv    => returns the details for Tuzla airport in CSV format
   http://api.vateud.net/airports/LQSA        => returns the details for Sarajevo airport as HTML (part of the API web interface)

Creating and editing airport records

This is done via the API backend by vACC staff with API accounts. The interface is self explanatory and looks like this:

Link to image

Staff members can only edit the records of the airports the belong to their respective vACC's countries.

P. Approved ATC frequencies

Fetching all VATEUD approved ATC frequencies

These are endpoints of the type: `http://api.vateud.net/frequencies` + `format type extension`

__Examples:__

   http://api.vateud.net/frequencies.json   #=> returns all EUD ATC freqs in JSON format
   http://api.vateud.net/frequencies.xml    #=> returns all EUD ATC freqs in XML format
   http://api.vateud.net/frequencies.csv    #=> returns all EUD ATC freqs in CSV format
   http://api.vateud.net/frequencies        #=> returns all EUD ATC freqs as HTML (part of the API web interface)

Scoping ATC frequencies per vACC

These are endpoints of the type: `http://api.vateud.net/frequencies/` + `vACC code` + `format type extension`

The full list of vACC codes can be seen at [http://api.vateud.net/frequencies](http://api.vateud.net/frequencies)

__Examples:__

   http://api.vateud.net/frequencies/BHZ.json    => returns all Bosnia freqs in JSON format
   http://api.vateud.net/frequencies/MALT.xml    => returns all Malta freq in XML format
   http://api.vateud.net/frequencies/NETH.csv    => returns all Netherlands freqs in CSV format
   http://api.vateud.net/frequencies/AUST        => returns all Austrian freqs as HTML (part of the API web interface)

Q. ATC Bookings and m[Mod - Happy Thoughts] bookings

Individual ATC bookings

Registered backend members now have the ability to create, edit and delete ATC bookings that are synchronized with the VATBOOK service (vroute, etc). Look for the "ATC Bookings" entry in the "Events and bookings" menu.

Users can also update or delete existing bookings, but only if they were initially created by themselves.

M[Mod - Happy Thoughts] bookings

When needed, backend users can also create m[Mod - Happy Thoughts] bookings (multiple bookings at once) by uploading a CSV file with the desired bookings details. Look for the "M[Mod - Happy Thoughts] Bookings" entry in the "Events and bookings" menu.

The following rules apply:

The CSV file should be UTF encoded (Unicode). Legacy latin, etc encodings will work as well granted that non-latin characters are avoided
The CSV file should have 4 entries per line, separated with commas `,`. Those entries in their respective order are: `Controller name and surname`, `ATC position`, `Starting date and time of the ATC session`, `Ending date and time of the ATC session`. All times are zulu (UTC).
The m[Mod - Happy Thoughts] created bookings can later be individually edited or deleted if needed, but only by the user who originally created the m[Mod - Happy Thoughts] booking
Both date/time entries in the CSV file should have the following syntax: `YYYY-MM-DD HH:MM:SS`

Example CSV file syntax:

    Svilen V[Mod - Happy Thoughts]ilev,LQTZ_APP,2013-12-19 13:00:00,2013-12-19 15:00:00
   Mirza Ibrahimovic,LQBK_APP,2013-12-19 14:00:00,2013-12-19 16:00:00
   Nikola Tutoric,LQMO_APP,2013-12-19 15:00:00,2013-12-19 17:00:00
   Adam Stanojevic,LQSA_APP,2013-12-19 18:00:00,2013-12-19 21:00:00

R. Squawk ranges

Public endpoint to pull all VATEUD allocated squawk ranges.

The endpoint is of the type: `http://api.vateud.net/squawks` + `format type extension`

Examples:

   http://api.vateud.net/squawks.json   => returns all squawks in JSON format
   http://api.vateud.net/squawks.xml    => returns all squawks in XML format
   http://api.vateud.net/squawks.csv    => returns all squawks in CSV format
   http://api.vateud.net/squawks        => returns all squawks as HTML (part of the API web interface)

That's pretty much it! Enjoy, feedback welcome

Edited February 5, 2014 at 11:45 AM by Guest

July 29, 2013 at 02:35 PM

Using the Authenticated endpoints with an access token (Tutorial)

There seems to be some confusion about how to use the access tokens and authenticated endpoints. So even though it's all written in the docomeentation, let me try to elaborate a bit and clear out some common misconceptions first and then give an example implementation:

The access tokens are NOT part of the request URLs, they must be sent as headers along with the request
The API endpoints / URLs are not normally something you paste in a browser: they serve a response to a request sent by an http client, typically from inside your own web application
The most widely used and well known http client is curl and apart from being available as a standalone command-line tool, there are curl wrappers for virtually any programming language available. There are also numerous alternatives to curl, some of them language specific.
VATEUD API follows the REST-ful convention, meaning you don't send POST requests when you only need reading the data. Right now all VATEUD API endpoints are read only and hence all requests processed are GET requests.
The syntax of sending headers along with a GET request varies from client to client and from language to language. Refer to the docomeentation of the client you're using and the language you're using.

And now here's an example implementation in Ruby on Rails using the two most pouplar http clients for Ruby: curb (the ruby curl imlpementation) and faraday. Choosing one over the other is a matter of preference and has no effect on the end result. The example is based on Rails 4 with Ruby 2.0. The view is rendered with HAML for simplicity.

In your Gemfile:

gem 'haml'
gem 'curb'  # if using curb
gem "faraday"  # if using faraday

In your model:

Option A: If using curb:

cl[Mod - Happy Thoughts] Member < ActiveRecord::Base
 def self.members_from_api
   response = Curl::Easy.http_get("api.vateud.net/emails/fyrm.json") do |curl|
     curl.headers['Authorization'] = 'Token token="your-vacc-access-token-here"'      
   end
   JSON.p[Mod - Happy Thoughts](response.body_str)
 end
end

Option B: If using faraday:

cl[Mod - Happy Thoughts] Member < ActiveRecord::Base
 def self.members_from_api
   response = Faraday.get 'http://api.vateud.net/emails/fyrm.json' do |faraday|
     faraday.headers['Authorization'] = 'Token token="your-vacc-access-token-here"'  
   end
   JSON.p[Mod - Happy Thoughts](response.body)
 end
end

In your controller:

cl[Mod - Happy Thoughts] MembersController < ApplicationController  
 def index
   @members = Member.members_from_api
 end
end

In your view:

%h2 Members from API
%table
 %tr
   %th Vatsim ID
   %th Name
   %th Email
 - for member in @members
   %tr
     %td= member["cid"]
     %td= "#{member['firstname']} #{member['lastname']}"
     %td= mail_to member["email"], "Send email"

What this will give you is a simple HTML table that looks like this:

Of course, how exactly you p[Mod - Happy Thoughts] the data and visualize it is up to you, but I wanted to give you an example of how to make authenticated API calls. You most likely do want to somehow cache the data or store/update it locally, but those are details.

If someone wants to post an implementation example from other languages/frameworks: go ahead

August 9, 2013 at 09:11 AM

Update: HTML wrapper added to all public endpoints.

Omitting the format extension in a call will now result in an HTML response: part of the API web interface and more convenient for human reference.

For an overview of the web interface just head over to api.vateud.net and have a look at the menus there.

August 15, 2013 at 04:04 PM

Update:

H. Airport Charts

These are public endpoints of the type: "http://api.vateud.net/charts/" + airport ICAO code + format type extension

Omitting the format type extension will return an html response with a chart listing (part of the API web interface)

The response will return 4 attributes for each chart:

ICAO - the code of the airport the chart refers to
name - the name of the chart
url_aip - link to the official source of the chart
url_charts_aero - link to the cached version of the chart at charts.aero

All chart responses are cached, the expiration time is currently set at 2 hours.

Examples:

   http://api.vateud.net/charts/lowi.json              #=> returns all Innsbruck charts in JSON format  
   http://api.vateud.net/charts/EGLC.xml               #=> returns all London City charts in XML format
   http://api.vateud.net/charts/lgav.csv               #=> returns all Athens airport charts in CSV
   http://api.vateud.net/charts/loww                   #=> returns an HTML listing of all Vienna charts

The chart listings are automatically synchronized with RW sources and are always current. Note, we only provide links to the publications, not physical files.

Not to be used for real world navigation!

So, no more excuses for outdated charts anywhere on vACC / event websites

Enjoy!

August 17, 2013 at 04:45 AM

Do you have a listing of all the countries your chart API supports?

Thanks,

Rahul

August 17, 2013 at 09:16 AM

Look here:

https://charts.aero/coverage

August 19, 2013 at 01:43 PM

Update:

I. Member Validation

This endpoint is of the type: "http://api.vateud.net/members/validate/".

It receives a member cid and email (sent along a GET request as headers) and matches them against the DB.

It returns `true` if a matching cid/email pair is found or otherwise returns `false`.

Useful for vACCs that run user registration checks on their websites to avoid bot registrations and (to a certain extent) impersonation.

Examples:

    
   # Curl command line:

   curl api.vateud.net/members/validate -H 'cid: 1175035' -H 'email: [email protected]'  #=> true
   curl api.vateud.net/members/validate -H 'cid: 1175036' -H 'email: [email protected]'  #=> false

   # An example Ruby method

   def validate_member(cid, email)
     response = Curl::Easy.http_get("api.vateud.net/members/validate") do |curl|
       curl.headers['cid'] = cid
       curl.headers['email'] = email
     end    
   end

Enjoy!

P.S. Even though it hurts my eyes and my Ruby heart, to make life easier for the PHP programmers I've changed the validation endpoint returns to "0" or "1" instead of "true/false". Docomeentation updated accordingly. To all Ruby folks out there - a reminder: caution, Ruby treats the "0" integer as "true", make sure you do an explicit type/value conversion.

August 21, 2013 at 02:53 PM

Update

J. Single member details

This endpoint is of the type: `http://api.vateud.net/members/id/` + `vatsim cid` + format type extension.

Omitting the format type extension will return an html response with the member details (part of the API web interface)

The data and logic is exactly the same as with other "members" endpoints with the only difference that this one only returns the details of a single member, identified by their vatsim CID.

Examples:

    http://api.vateud.net/members/id/1264903.json    #=> returns member's details in JSON format  
   http://api.vateud.net/members/id/1092003.xml     #=> returns member's details in XML format  
   http://api.vateud.net/members/id/973575.csv      #=> returns member's details in CSV format  
   http://api.vateud.net/members/id/890112          #=> returns member's details as HTML

Enjoy

August 22, 2013 at 02:14 PM

Augmented on vACC request:

The single member details endpoint (J.) has been revised to optionally accept vacc access token. If such a token is present and valid, the returned set of results will also include the email and suspension expiration date.

Here's the full description:

J. Single member details (revised)

This endpoint is of the type: `http://api.vateud.net/members/id/` + `vatsim cid` + format type extension.

Omitting the format type extension will return an html response with the member details (part of the API web interface)

The data and logic is exactly the same as with other "members" endpoints with the only difference that this one only returns the details of a single member, identified by their vatsim CID.

This endpoint allows optionally sending a vACC access token as a header in the following syntax:

'Authorization: Token token="your-vacc-access-token"'.

If a valid access token is received, the member details returned will be augmented with 2 extra attributes: member email address and suspension expiration date (if any). This extra data will only be included if the submitted vacc token matches the affeccted member vacc.

If no access token is sent or the access token is invalid or the access token does not match the queried member vacc, then the standart set of public details will be returned, not including the email, etc.

Examples:

   http://api.vateud.net/members/id/1264903.json    #=> returns member's details in JSON format  
   http://api.vateud.net/members/id/1092003.xml     #=> returns member's details in XML format  
   http://api.vateud.net/members/id/973575.csv      #=> returns member's details in CSV format  
   http://api.vateud.net/members/id/890112          #=> returns member's details as HTML  

   curl api.vateud.net/members/id/890112.json -H 'Authorization: Token token="valid-access-token"'
                       #=> returns augmented set of member's details (including email) in json format
   curl api.vateud.net/members/id/890112.xml -H 'Authorization: Token token="valid-access-token"'
                       #=> returns augmented set of member's details (including email) in xml format

   curl api.vateud.net/members/id/890112.json -H 'Authorization: Token token="invalid-access-token"'
               #=> returns standart public set of member's details (not including email) in json format
   curl api.vateud.net/members/id/890112.csv -H 'Authorization: Token token="invalid-access-token"'
                       #=> returns standart set of member's details (not including email) in csv format

Enjoy!

August 23, 2013 at 06:58 AM

Man, an update every few days with new features.......this is getting more and more impressive I haven't had the time to implement the original request yet

August 23, 2013 at 10:57 AM

Man, an update every few days with new features.......this is getting more and more impressive I haven't had the time to implement the original request yet

It's all your fault, Todor, you started an avalanche!

P.S. The history got lost in the recent forum rollback, but this API wouldn't have happened without a request initially coming from Todor. Then Luca Benelli joined with some ideas and advice and from there it all escalated

August 25, 2013 at 07:46 AM

Hey don't blame me, all I wanted was a small thing....not that masterpiece :D:D

August 25, 2013 at 06:50 PM

That API is great, especially charts. Now we have all charts one click away. Thanks very much!

Is it possible to fetch data about only one online station? I'd like to fetch some information about pilots from my airline while they are online.

August 27, 2013 at 01:50 PM

That API is great, especially charts. Now we have all charts one click away. Thanks very much!

Is it possible to fetch data about only one online station? I'd like to fetch some information about pilots from my airline while they are online.

Thanks, Slawomir!

Regarding the online data: the way it currently works is it filters data by airport(s), FIR(s). There is no possibility in the current implementation to filter out a subset of data based on pilot callsigns, but I can see this being useful for VAs and I'll add it to the list for the future.

August 27, 2013 at 01:55 PM

Thanks for answer.

This option would also lower load of servers, as I could get only 1-2kB instead of 300kB of data.

Technically it's not a problem to filter 300kB file after download, but it is far from optimal solution.

October 3, 2013 at 08:50 PM

Update:

Overriding chart titles

Oc[Mod - Happy Thoughts]ionally, chart names (labels), as provided from our data sources, might not match the physical chart name. We have now implemented the logic and backend interface for easily overriding such discrepancies. If you notice a title issue, please submit a task to VATEUD7, specifying the airport ICAO and the correct chart title.

October 5, 2013 at 04:16 PM

As promised

Update:

K. Online stations data by callsign

This portion of the API is powered by the vatsim_online library. If you're curious to see in detail how it works and the full array of options it provides, head over to the docomeentation.

These are public endpoints of the type:

"http://api.vateud.net/online/callsign/" + callsign filter + format type extension

The callsigns can designate both pilot and ATC stations.

The callsign filter is a string of full or partial, one or multiple comma separated callsigns that will be used to filter out the requested online data. They are not case sensitive. For example you can use the "baw" filter to show all British Airways flights, or "loww,aua" filter to show all atc stations for Vienna airport and all Austrian Airlines flights, or "ach, afr" filter to show all Air Child and Air France flights, etc

Examples:

http://api.vateud.net/online/callsign/baw.json        #=> returns all British Airways flights in JSON format  
http://api.vateud.net/online/callsign/afr.xml         #=> returns all Air France flights in XML format  
http://api.vateud.net/online/callsign/aua,LOWW.csv    #=> returns all Austrian Airlines flights and all
                                                         Vienna airport stations in CSV format  
http://api.vateud.net/online/callsign/ach             #=> returns all Air Child flights as HTML (part of the API web interface)

....etc.....

Note: The online stations responses are all being cached with expiration time set to 5 minutes. The online stations data is not limited to EUD, you can use it for any stations on the network.

Enjoy

October 5, 2013 at 04:22 PM

Thanks for this new function.

Is it possible to add longitude and latitude to this? I'd like to use this data on map.

October 5, 2013 at 04:28 PM

You're welcome!

It already has lat, long and all the other data that VATSIM knows about. You'll find all the data in the json, xml and csv formats.

Look here for example: http://api.vateud.net/online/callsign/baw.xml

What you see in the HTML is stripped down to just a general overview, and that's valid for all endpoints. The primary focus and intention of the API, after all, is to provide a programatically usable data sources for developers, the HTML interface is by the by, just for fluff

October 20, 2013 at 02:43 PM

Update: (it's a big one this time: 101 files changed, 2161 insertions, 712 removals)

L. Events management (calendar)

The VATEUD events management and calendar API is designed to solve the issue of having multiple standalone (isolated) calendar solutions for each vACC and for VATEUD separately and to overcome the limitations of the existing EUD calendar, which is a self contained "silo" with web interface only, and no ways of programmatically reading, creating or updating event data. The new system provides event organizers across EUD with a single point of posting and updating their event announcements following the principle of "publish once (or edit once), display anywhere". This also ensures that all pilots will have the same, full event information wherever they look.

The events management API provides the following abilities:

1. Create, edit, delete events

- a) Via web interface

- b) Programmatically, via authenticated REST-ful API calls

2. Retrieve and scope events

- in 4 different formats JSON, XML, CSV and ICS/iCAL for integration with calendar tools/apps

- scoped either globally (all VATEUD events) or per vACC (each vACCs events listing)

These abilities ensure the following use cases are satisfied:

vACCs don't have to maintain their own calendar systems, they can pull their vACC events from the EUD API in any convenient format and just visualize them on their websites.
vACCs that maintain their own calendar systems can easily synchronize their data with the EUD calendar when creating or updating an event on their end by simultaneously sending calls to the EUD API
Any 3rd party service can use the events API to list VATEUD events. This is how, for example, the new VATEUD website will be getting its event data
The choice between using web backend for events management or using the RESTful API gives both technical and non-technical users/vaccs the opportunity to utilize the system without being inconvenienced

Reading (retrieving) event data

For retrieving the unscoped VATEUD events data (for all vaccs), use the following endpoint:

`http://api.vateud.net/events + format type extension`

Examples:

   http://api.vateud.net/events.json    #=> returns all EUD events in JSON format
   http://api.vateud.net/events.xml     #=> returns all EUD events in XML format
   http://api.vateud.net/events.csv     #=> returns all EUD events in CSV format
   http://api.vateud.net/events.ics     #=> returns all EUD events in ICS format
   http://api.vateud.net/events         #=> returns all EUD events as HTML listing (part of the API web frontend)

For retrieving the Events data scoped by vACC (events by a particular vacc only), use the following endpoint:

`http://api.vateud.net/events/vacc/vacc_code + format type extension`

The list of vACC codes is available at http://api.vateud.net/subdivisions

Examples:

 
  http://api.vateud.net/events/vacc/BHZ.json   #=> returns all Bosnia & Herzegovina events in JSON format
   http://api.vateud.net/events/vacc/AUST.xml   #=> returns all Austria events in XML format
   http://api.vateud.net/events/vacc/GER.csv    #=> returns all Germany events in CSV format
   http://api.vateud.net/events/vacc/GRЕ.ics    #=> returns all Greek events in ICS format
   http://api.vateud.net/events/vacc/BHZ        #=> returns all Bosnia & Herzegovina events as HTML (part of the API web frontend)

For retrieving the details of an individual event, use the following endpoint:

`http://api.vateud.net/events/event_id + format type extension`

Examples:

   http://api.vateud.net/events/4.json  #=> returns the details with event with id 4 in JSON format
   http://api.vateud.net/events/1.xml   #=> returns the details with event with id 1 in XML format
   http://api.vateud.net/events/2.csv   #=> returns the details with event with id 2 in CSV format
   http://api.vateud.net/events/3.ics   #=> returns the details with event with id 3 in ICS format
   http://api.vateud.net/events/1       #=> returns the details with event with id 1 as HTML (part of the API web frontend)

Creating, editing and deleting events programmatically

In order to use the RESTful API CRUD (create, edit and delete endpoints) you'll need an API access token for your vACC. These 3 endpoints only accept authenticated calls. Read above on how to request an API token.

Event record attributes

Each event record can accept the following attributes:

`title` - the event name
`subtitle` - snappy short event summary, i.e. "ICAO fully staffed"
`airports` - a comma separated list of the event airports (ICAO codes)
`description` - the event description. No length limit, can contain HTML
`banner_url` - a link to your banner image, if any
`starts` - starting date and time for the event (zulu) in the following format: "2013-10-27T20:00:00Z". The T letter denotes the beginning of the time string, separating the date and time.
`ends` - ending date and time for the event (zulu) in the following format: "2013-10-27T20:00:00Z". The T letter denotes the beginning of the time string, separating the date and time.
`vaccs` - the vACCs (one or many) that are organizing the event. Determined programmatically by the access token, not editable via remote calls
`id` - unique numeric identifier, returned by the application on create and update calls, not editable

RESTful principle explained

The VATEUD API follows the RESTful convention, meaning you send remote calls to a certain endpoint (optionally including an id), plus you also send in JSON data for the record that you want published/changed and you also authenticate yourself on behalf of a vACC with an API token. The type of HTTP request that you're sending in determines the type of action that you want in the following way:

GET requests are for reading records
POST requests are for creating records
PUT requests are for updating records
DELETE requests are for destroying records

Creating an event record

In order to create an event, you send an HTTP POST request to `http://api.vateud.net/events` with the JSON details of the new event and with your API token (sent as a HEADER along with the request)

Example:

curl -X POST -H "Content-Type: application/json" -d '{"airports":"LBSF,LQSA","banner_url":"http://domain.net/image.jpg",
     "description":"example description, can contain HTML","ends":"2013-10-27T22:00:00Z","starts":"2013-10-27T20:00:00Z",
     "subtitle":"event subtitle","title":"Our Grand Event"}' http://api.vateud.net/events -H 'Authorization: Token token="your-vacc-authorization-token"'

Notes:

The example is a command line CURL call in a UNIX-based OS. The exact syntax will vary depending on the http client implementation and the language you're using. Refer to your http client's docomeentation for full reference.
The order of attributes in the JSON string is irrelevant. In the above example they're ordered alphabetically, but you can do as you please, just remember to wrap both the attribute name and the attribute value in quotes, use colon between the name (label) and the value, and separate the pairs with commas
In the example I have added a header specifying the MIME type of the data that I'm sending: in our case application/json. Strictly speaking this is not necessary. The application expects json and will recognize and accept it even without Content-Type header. Nevertheless it's a general good practice to declare the content type when sending data across, so better do it for consistency.
Note: the Authentication token is sent along as a HEADER!
If the call has been successful and the record is created, the endpoint will return the new record as JSON, including all attributes PLUS the newly created record ID. You probably want to catch and store the ID if you want to be able to programmatically edit or delete this record in the future.
The new event will be tagged and [Mod - Happy Thoughts]igned to the vACC that corresponds to the authentication token used
No record will be created without an authentication token

Editing (updating) an event record

In order to edit (update) an event, you send an HTTP PUT request to `http://api.vateud.net/events/event_id` with the JSON details

that you want changed and with your API token (sent as a HEADER along with the request). Note you need to p[Mod - Happy Thoughts] the event ID to the URL

Example:

curl -X PUT -H "Content-Type: application/json" -d '{"subtitle":"New subtitle","title":"New title"}'
      http://api.vateud.net/events/1 -H 'Authorization: Token token="your-vacc-access-token"'

Notes:

You only need to p[Mod - Happy Thoughts] the attributes that you want changed, not all attributes. The order is irrelevant.
In the example above, the record changed has an ID of 1
The Authentication token is sent along as a HEADER!
If the call has been successful and the record is updated, the endpoint will return the full record as JSON, including all attributes plus the id.
The record will not be updated (error message returned) without an authentication token
The record will not be updated (error message returned) if the authentication token's vACC doesn't match the event record vACC

Deleting an event record

In order to delete an event, you send an HTTP DELETE request to `http://api.vateud.net/events/event_id` with your API token (sent as a HEADER along with the request). Note you need to p[Mod - Happy Thoughts] the event ID to the URL, but you don't need to send any JSON data at this time

Example:

    curl -X DELETE http://localhost:3000/events/3 -H 'Authorization: Token token="your-vacc-access-token"'

Notes:

In the example above, the record changed has an ID of 3
The Authentication token is sent along as a HEADER!
The record will not be deleted (error message returned) without an authentication token
The record will not be deleted (error message returned) if the authentication token's vACC doesn't match the event record vACC

Creating, editing and deleting events via the web backend interface

The backend administrative interface for the VATEUD API is accessible via http://api.vateud.net/admin.

There's also a link called "Staff Zone" in the menu pointing that way.

The backend requires registration, which is open to all users.

The backend functionality available to individual users is dependant on the user's roles. Initially all users start with no roles and they have access to no functionality. When logged in they see a blank dashboard. So don't panick, when you initially register, log in and see nothing useful A user needs to be [Mod - Happy Thoughts]igned one or multiple roles by an admin in order to get backend functionality and menus accessible.

The currently available roles are:

`admin` - unrestricted access
`events` - access to events management
`staff` - access to vACC details and staff lists management (pending future update)

Admins are notified by email when a new user signs up, and after checking their credentials, they'll [Mod - Happy Thoughts]ign him roles, usually within the day.

We will only enable accounts created by vACC staff members.

Users with an "Events" role will see an interface similar to the one below:

Link to image

Search and export functionality is available for convenience.

The Add and Edit forms look like this and are self explanatory (the description field supports rich text formatting and comes with a WYSIWYG editor):

Link to image

The following restrictions apply when manipulating event records via the web backend:

a user can only edit an event if the event's vACC matches the user vacc
a user can only delete an event if the event's vACC matches the user vacc

Initial post updated accordingly. Enjoy

October 23, 2013 at 03:09 PM

Update:

M. vACC profiles

These endpoints allow fetching the general vACC data, either globally (all EUD subdivisions) or indivisually per vACC. Through the API vACC data can be distributed and visualized on any 3rd party website, including the new EUD website.

The following attrbiutes are exposed for each vACC:

`code` - unique identifying subdivision code, as defined in VATSIM database
`name` - the vACC name
`website` - the vACC website URL
`introtext` - introductory description of the vACC
`official` - boolean flag, marks the vACC as official or unofficial

Editing vACC records

With the introduction of this portion of the API, vACC records transition from EUD-managed to self-managed. Each vACC has the ability to edit their own records without being dependant on EUD staff.

vACC staff members with API accounts and sufficient levels of permission can edit their vACC profiles via the backend web interface of the API.

The web interface for editing vACC records is self explanatory and similar to the pictured below:

Link to image

Notes:

vACC staff members can only edit the record for the vACC they belong to
All changes are logged, tracked and reversible to prevent abuse or accidental data loss
Deleting or creating subdivision is, of course, not possible via the interface
One or more countries can be [Mod - Happy Thoughts]igned ([Mod - Happy Thoughts]ociated) with a particular vACC
The introtext supports HTML and the interface comes with a WYSIWYG editor for that field

Reading vACC records

Fetching all vACC records

This is a public endpoint of the type: `http://api.vateud.net/subdivisions` + `format type extension`

Examples:

   http://api.vateud.net/subdivisions.json   #=> returns all vACCs data in JSON format
   http://api.vateud.net/subdivisions.xml    #=> returns all vACCs data in XML format
   http://api.vateud.net/subdivisions.csv    #=> returns all vACCs data in CSV format
   http://api.vateud.net/subdivisions        #=> returns all vACCs data as HTML (part of the API web interface)

Fetching individual vACC data

These are public endpoints of the type: `http://api.vateud.net/subdivisions/` + `vacc code` + `format type extension`

The full list of vACC codes can be found at http://api.vateud.net/subdivisions

Examples:

 
   http://api.vateud.net/subdivisions/BLUX.json  => returns vACC BeLux details in JSON format
   http://api.vateud.net/subdivisions/ITA.xml    => returns vACC Italy details in XML format
   http://api.vateud.net/subdivisions/SLOV.csv   => returns vACC Slovenia details in CSV format
   http://api.vateud.net/subdivisions/BHZ        => returns vACC B&H details as HTML (part of the API web interface)

Initial post has been updated accordingly.

Coming up in next update: self managed vACC Staff listings, via web interface and REST-ful calls.

Enjoy

October 24, 2013 at 03:51 PM

Update:

N. Self managed vACC Staff Members listings

The VATEUD vACC Staff Members API is designed to enable vACC staff to self-manage and maintain their vACC staff records, via web interface or programmatically, following the principle of "publish once (or edit once), display anywhere". It has built-in mechanisms of tracking and confirming staff changes by EUD staff to avoid abuse or accidental data loss.

The vACC Staff members API provides the following abilities:

1. Create, edit, delete staff members

- a) Via web interface

- b) Programmatically, via authenticated REST-ful API calls

2. Retrieve and scope staff members

- in 3 different formats: JSON, XML, CSV

- scoped either globally (all vACC staff members) or per vACC (each vACCs staff listing)

- ability to retrieve the details of an individual vACC staff position

Any 3rd party service can use the staff members API to list vACC staff. This is how, for example, the new VATEUD website will be getting its staff data, and it can be easily implemented on individual vACC sites as well.

The choice between using web backend for staff management or using the RESTful API gives both technical and non-technical users/vaccs the opportunity to utilize the system without being inconvenienced.

Reading (retrieving) staff members data

For retrieving the unscoped VATEUD staff members data (for all vaccs), use the following endpoint:

`http://api.vateud.net/staff_members` + `format type extension`

**Examples:**

   http://api.vateud.net/staff_members.json    #=> returns all EUD staff members in JSON format
   http://api.vateud.net/staff_members.xml     #=> returns all EUD staff members in XML format
   http://api.vateud.net/staff_members.csv     #=> returns all EUD staff members in CSV format
   http://api.vateud.net/staff_members         #=> returns all EUD staff members as HTML listing (part of the API web frontend)

For retrieving the staff members data scoped by vACC (staff listings for a particular vacc only), use the following endpoint:

`http://api.vateud.net/staff_members/vacc/` + `vacc_code` + `format type extension`

The list of vACC codes is available at http://api.vateud.net/subdivisions

**Examples:**

 
   http://api.vateud.net/staff_members/vacc/BHZ.json   #=> returns all Bosnia & Herzegovina staff members in JSON format
   http://api.vateud.net/staff_members/vacc/AUST.xml   #=> returns all Austria staff members in XML format
   http://api.vateud.net/staff_members/vacc/GER.csv    #=> returns all Germany staff members in CSV format
   http://api.vateud.net/staff_members/vacc/BHZ        #=> returns all Bosnia & Herzegovina staff members as HTML (part of the API web frontend)

For retrieving the details of an individual staff position, use the following endpoint:

`http://api.vateud.net/staff_members/` + `staff member id` + `format type extension`

**Examples:**

   http://api.vateud.net/staff_members/212.json  #=> returns the details for staff member with id 212 in JSON format
   http://api.vateud.net/staff_members/191.xml   #=> returns the details for staff member with id 191 in XML format
   http://api.vateud.net/staff_members/185.csv   #=> returns the details for staff member with id 185 in CSV format
   http://api.vateud.net/staff_members/159       #=> returns the details for staff member with id 159 as HTML (part of the API web frontend)

Creating, editing and deleting staff members programmatically

In order to use the RESTful API CRUD (create, edit and delete endpoints) you'll need an API access token for your vACC.

These 3 endpoints only accept authenticated calls. Read above on how to request an API token.

Staff member attributes

Each staff member record can accept the following attributes:

`callsign` - the staff position callsign, i.e. "ACCSLACK5"
`position` - the position description, i.e. "Leisure Manager"
`cid` - the Vatsim ID of the person occupying the position. Can be blank for vacant positions
`email` - the staff position email. Can be blank for vacant positions
`priority` - mandatory integer (number) attribute, designates the relative order of the posiotion in regards to other positions within the same vACC. I.e. position with priority 1 will be listed abover position with priority 2.
`vacc_code` - the vACC code of the staff member. Determined programmatically by the access token, not editable via remote calls
`id` - unique numeric record identifier, returned by the application on create and update calls, not editable

RESTful principle explained (again)

The VATEUD API follows the RESTful convention, meaning you send remote calls to a certain endpoint (optionally including an id), plus you also send in JSON data for the record that you want published/changed and you also authenticate yourself on behalf of a vACC with an API token. The __type of HTTP request__ that you're sending in determines the type of action that you want in the following way:

GET requests are for __reading__ records
POST requests are for __creating__ records
PUT requests are for __updating__ records
DELETE requests are for __destroying__ records

Creating a staff member record

In order to create an staff member, you send an HTTP __POST request__ to `http://api.vateud.net/staff_members` with the JSON details

of the new position and with your API token (sent as a HEADER along with the request)

Example:

    curl -X POST -H "Content-Type: application/json" -d '{"callsign":"ACCBIH8","position":"New Test Position",
       "cid":"12345678","email":"[email protected]","priority":"8"}' http://api.vateud.net/staff_members 
        -H 'Authorization: Token token="your-vacc-access-token"'

Notes:

The example is a command line CURL call in a UNIX-based OS. The exact syntax will vary depending on the http client implementation and the language you're using. Refer to your http client's docomeentation for full reference.
The order of attributes in the JSON string is irrelevant, just remember to wrap both the attribute name and the attribute value in quotes, use colon between the name (label) and the value, and separate the pairs with commas
In the example I have added a header specifying the MIME type of the data that I'm sending: in our case application/json. Strictly speaking this is not necessary. The application expects json and will recognize and accept it even without Content-Type header. Nevertheless it's a general good practice to declare the content type when sending data across, so better do it for consistency.
Note: the Authentication token is sent along as a HEADER!
If the call has been successful and the record is created, the endpoint will return the new record as JSON, including all attributes PLUS the newly created record ID. You probably want to catch and store the ID if you want to be able to programmatically edit or delete this record in the future.
The new staff member position will be tagged and [Mod - Happy Thoughts]igned to the vACC that corresponds to the authentication token used
No record will be created without an authentication token

Editing (updating) a staff member record

In order to edit (update) a staff member, you send an HTTP __PUT request__ to `http://api.vateud.net/staff_members/staff_member_id` with the JSON details that you want changed and with your API token (sent as a HEADER along with the request). Note you need to p[Mod - Happy Thoughts] the

staff member ID to the URL

Example:

 
  curl -X PUT -H "Content-Type: application/json" -d '{"cid":"12345788","email":"[email protected]"}'
      http://api.vateud.net/staff_members/474 -H 'Authorization: Token token="your_vacc_access_token"'

Notes:

You only need to p[Mod - Happy Thoughts] the attributes that you want changed, not all attributes. The order is irrelevant.
In the example above, the record changed has an ID of 474
The Authentication token is sent along as a HEADER!
If the call has been successful and the record is updated, the endpoint will return the full record as JSON, including all attributes plus the id.
The record will not be updated (error message returned) without an authentication token
The record will not be updated (error message returned) if the authentication token's vACC doesn't match the staff member record vACC

Deleting a staff member record

In order to delete a staff member record, you send an HTTP __DELETE request__ to `http://api.vateud.net/staff_members/staff_member_id` with your API token (sent as a HEADER along with the request). Note you need to p[Mod - Happy Thoughts] the event ID to the URL, but you don't need to send any JSON data at this time

Example:

   curl -X DELETE http://api.vateud.net/staff_members/471 -H 'Authorization: Token token="your_vacc_access_token"'

Notes:

In the example above, the record deleted has an ID of 471
The Authentication token is sent along as a HEADER!
The record will not be deleted (error message returned) without an authentication token
The record will not be deleted (error message returned) if the authentication token's vACC doesn't match the staff member record vACC

Creating, editing and deleting staff members via the web backend interface

The backend administrative interface for the VATEUD API is accessible via http://api.vateud.net/admin.

There's also a link called "Staff Zone" in the menu pointing that way.

The backend requires registration, which is open to all users.

The backend functionality available to individual users is dependant on the user's roles. Initially all users start with no roles and they have access to no functionality. When logged in they see a blank dashboard. So don't panick, when you initially register, log in and see nothing useful A user needs to be [Mod - Happy Thoughts]igned one or multiple roles by an admin in order to get backend functionality and menus accessible.

The currently available roles are:

`admin` - unrestricted access
`events` - access to events management
`staff` - access to vACC details and staff lists management

Admins are notified by email when a new user signs up, and after checking their credentials, they'll [Mod - Happy Thoughts]ign him roles, usually within the day.

We will only enable accounts created by vACC staff members.

Users with a "Staff" role will see an interface similar to the one below:

Link to image

Search and export functionality is available for convenience.

The Add and Edit forms look like this and are self explanatory:

Link to image

The following restrictions apply when manipulating event records via the web backend:

A user can only edit a staff member if the staff member's vACC matches the user vacc
A user can only delete a staff member if the staff member's vACC matches the user vacc
All changes are logged, tracked and reversible to prevent abuse or accidental data loss
A `vateud_confirmed` flag is attached to each record. The flag is set to "false" by default and also reset from "true" to "false" whenever an existing staff member is edited, either via the web interface or programmatically. Only EUD staff with admin level of access to the API can "confirm" staff member records, thus setting the flag to "true". This is to avoid errors and potential abuse, and to make sure EUD staff has an easy way to monitor vACC staff changes as they happen. This flag is for internal reference of EUD staff only and has no impact of the record's availability.

Initial post has been updated accordingly.

Enjoy!

October 25, 2013 at 12:00 PM

Update, based on feedback:

One question though and sorry if this has been discussed somewhere earlier: would it be possible to add a recurring flag for the events to the Events management database? I do understand that this somehow pollutes the calendar as some of the events are just forgotten there so I'll of course understand should you say no to this request.

It hasn't been discussed before, but I had it in mind.

I pushed an update today, that adds a "weekly" attribute flag when creating a new event, either via the web interface or via a remote POST request. :

* `weekly` - a boolean flag, can have "true" or "false" values. Only used when creating events, won't have any effect when editing an existing event. Causes the application to create 52 weekly instances of the event (1 year ahead). The day of the week and starting and ending times for each instance match the initial event values.


# Creating a recurring weekly event (by adding a "weekly":"true" attribute)

   curl -X POST -H "Content-Type: application/json" -d '{"airports":"LBSF,LQSA","banner_url":"http://domain.net/image.jpg",
     "description":"example description, can contain HTML","ends":"2013-10-27T22:00:00Z","starts":"2013-10-27T20:00:00Z",
     "subtitle":"weekly event subtitle","title":"Our Weekly Event","weekly":"true"}' http://api.vateud.net/events
     -H 'Authorization: Token token="your-vacc-authorization-token"'

As you can see, the "weekly"is just another event attribute that can be optionally sent when creating an event. When using the web interface, it's straightforward: it will display a checkmark field like this:

This is not true recurrence, but it will solve 90% of VATSIM use cases, plus giving the ability to selectively delete individual recurring instances of the event on vACCs discretion. I.e. if you decide that you can't do this week's weekly event for some reason, you can just delete that instance, while keeping the other occurrences in place. If we were to use a true recurrence, that would not be possible: deleting the event would have deleted all it's instances.

If needed in the future, I can add the ability to create monthly or bi-weekly events in the same manner.

And another question for the members list: would it be possible to add an inactive flag to the members list of the VACC which can be edited by the admins on the API site? I'd be more than happy to use the API on our VACC's website to list the members, but the returned list is quite huge compared to the actual number of active ATCs we have now on our roster. Of course another solution would be to store the inactivity flags on our side, but then it's getting a bit redundant again..

That's also done with today's update:

"active" flag has been added to member records and all EUD admins and vACC staff members with API backend access can edit this flag via the web interface. It's been also propagated via the json, xml and csv endpoints on the frontend. By default, as of now, all members with a VATSIM rank of 0 (Inactive/Suspended) have the "active" flag set to "false" and all other members have the active flag set to "true".

vACC staff with backend access will only be able to browse and manipulate the members of their respective vACCs. Only EUD admins can see the full listings.

For vACC Staff members the interface looks like this:

The docomeentation has been updated accordingly.

October 27, 2013 at 10:43 PM

Update:

O. Airport profiles

The airports API allows vACC to showcase some or all airports in their respective countries, and make the information available to any 3rd party web service that wants to use it, including event websites, individual vACC websites and the VATEUD website.

Creating airport records is only possible via the API backend for now. vACC staff members with API backend access can create, edit and destroy airport profiles.

Only part of the airport data is filled in and maintained by vACCs, and even a smaller subset of this data is mandatory. The majority of the data listed and available for each airport is obtained and updated programmatically via the airdata library. If you're interested in the technical details, read the docomeentation.

The following attributes are included for each airport:

vACC provided:

`icao` - mandatory, unique. The airport's ICAO identifier.
`iata` - mandatory. The airport's IATA code
`country` - mandatory. The airport's country, chosen from a list of EUD countries
`major` - a boolean field. Designates an airport as being a "major" one
`scenery_fs9_link` - link to FS9 scenery
`scenery_fsx_link` - link to FSX/P3D scenery
`scenery_xp_link` - link to X-Plane scenery
`description` - freetext description of the airport. Supports rich text format and the field comes with a WYSIWYG editor on the backend

Automatically obtained:

`name` - the airport's (or city) name
`elevation` - the airport's elevation in feet
`ta` - the airport's transition altitude
`msa` - the airport's minimum safe altitude
`lat` - the airport's latitude
`lon` - the airport's longitutde

Airport runways (automatically obtained)

`number` - the runway number (designator)
`course` - the runway course
`length` - the runway length in feet
`elevation` - the runway threshold elevation
`lat` - the latitude of the runway threshold
`lon` - the longitude of the runway threshold
`ils` - boolean; true if the runway is equipped with ILS
`ils_fac` - the ILS final aproach course
`ils_freq` - the ILS frequency
`glidepath` - the ILS glidepath angle. Defaults to 3 degrees for runways without ILS

Data structure and format differences

As you can see, it's a big set of data, and it's nested/structured in the API responses, so that all the primary vacc provided attributes are directly listed in the airport set, all the automatically obtained general details are grouped in a "data" subset, and all runways informtion is grouped in a "runways" subset which is nested below "data". The country data is isolated in a separate "country" subset, giving the country code and country name attributes.

Hence an exaple JSON repsonse will look like this:

    {"description":"<p><strong>Sarajevo International Airport</strong> description</p>\r\n",
   "iata":"SJJ","icao":"LQSA","major":true,"scenery_fs9_link":"http://vaccbih.info/downloads",
   "scenery_fsx_link":"http://vaccbih.info/downloads","scenery_xp_link":"http://vaccbih.info/downloads",
   "country":{"code":"BA","name":"Bosnia-Herzegovina"},"data":{"elevation":1708,"icao":"LQSA",
   "lat":43.824472,"lon":18.331767,"msa":8500,"name":"SARAJEVO","ta":9500,"runways":[{"course":115,
   "elevation":1643,"glidepath":3.2,"ils":true,"ils_fac":115,"ils_freq":110.7,"lat":43.829542000000004,
   "length":8530,"lon":18.318231,"number":"12"},{"course":295,"elevation":1690,"glidepath":3.0,"ils":false,
   "ils_fac":0,"ils_freq":0.0,"lat":43.821272,"length":8530,"lon":18.340303,"number":"30"}]}}

XML responses are structured in the same way. CSV responses are "flattened" to include all the general details. Due to the inability of the CSV format to store a subset of arbitrary size, runways information is not included in the CSV responses.

Fetching all EUD airports

These are endpoints of the type: `http://api.vateud.net/airports` + `format type extension`

Examples:

   http://api.vateud.net/airports.json   #=> returns all EUD airports in JSON format
   http://api.vateud.net/airports.xml    #=> returns all EUD airports in XML format
   http://api.vateud.net/airports.csv    #=> returns all EUD airports in CSV format
   http://api.vateud.net/airports        #=> returns all EUD airports as HTML (part of the API web interface)

Scoping the airports per country

These are endpoints of the type: `http://api.vateud.net/airports/country/` + `country code` + `format type extension`

The full list of EUD country codes can be seen at http://api.vateud.net/airports

Examples:

 
  http://api.vateud.net/airports/country/BA.json  #=> returns all Bosnia & Herzegovina airports in JSON format
   http://api.vateud.net/airports/country/BA.xml   #=> returns all Bosnia & Herzegovina airports in XML format
   http://api.vateud.net/airports/country/BA.csv   #=> returns all Bosnia & Herzegovina airports in CSV format
   http://api.vateud.net/airports/country/BA       #=> returns all Bosnia & Herzegovina airports as HTML (part of the API web interface)

Getting individual airport details

These are endpoints of the type: `http://api.vateud.net/airports/` + `ICAO code` + `format type extension`

Examples:

 
   http://api.vateud.net/airports/LQSA.json   => returns the details for Sarajevo airport in JSON format
   http://api.vateud.net/airports/LQMO.xml    => returns the details for Mostar airport in XML format
   http://api.vateud.net/airports/LQTZ.csv    => returns the details for Tuzla airport in CSV format
   http://api.vateud.net/airports/LQSA        => returns the details for Sarajevo airport as HTML (part of the API web interface)

Creating and editing airport records

This is done via the API backend by vACC staff with API accounts. The interface is self explanatory and looks like this:

Link to image

Staff members can only edit the records of the airports the belong to their respective vACC's countries.

So to make a long story short, with this update, and combining with the charts, notams and online stations data that are already available via the API, creating airport profiles that look like this is as simple as pie and there's no reason not to do it for your vACC or event websites We give you all the data: just visualize it the way you want and you're done, no need to manually fiddle with it or update it; set and forget.

Initial post has been updated accordingly.

Enjoy!

October 28, 2013 at 07:03 PM

Update:

P. Approved ATC frequencies

Fetching all VATEUD approved ATC frequencies

These are endpoints of the type: `http://api.vateud.net/frequencies` + `format type extension`

__Examples:__

   http://api.vateud.net/frequencies.json   #=> returns all EUD ATC freqs in JSON format
   http://api.vateud.net/frequencies.xml    #=> returns all EUD ATC freqs in XML format
   http://api.vateud.net/frequencies.csv    #=> returns all EUD ATC freqs in CSV format
   http://api.vateud.net/frequencies        #=> returns all EUD ATC freqs as HTML (part of the API web interface)

Scoping ATC frequencies per vACC

These are endpoints of the type: `http://api.vateud.net/frequencies/` + `vACC code` + `format type extension`

The full list of vACC codes can be seen at http://api.vateud.net/frequencies

__Examples:__

   http://api.vateud.net/frequencies/BHZ.json    => returns all Bosnia freqs in JSON format
   http://api.vateud.net/frequencies/MALT.xml    => returns all Malta freq in XML format
   http://api.vateud.net/frequencies/NETH.csv    => returns all Netherlands freqs in CSV format
   http://api.vateud.net/frequencies/AUST        => returns all Austrian freqs as HTML (part of the API web interface)

Enjoy

VATEUD API

Recommended Posts

Svilen Vassilev

Link to comment

Share on other sites

Top Posters In This Topic

Popular Days

Top Posters In This Topic

Popular Days

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Rahul Parkar

Link to comment

Share on other sites

Sam White 1214219

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Todor Atanasov 878664

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Todor Atanasov 878664

Link to comment

Share on other sites

Slawomir Wawak

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Slawomir Wawak

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Slawomir Wawak

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment

Share on other sites

Svilen Vassilev

Link to comment