Using the API
Getting started is relatively simple, as all the required Javascript and PHP functions are provided for you. The basic guidelines are as follows:
-
On the page which calls the API, you will need to include an html
<form>containing the dispatch options you would like to use. The<input>names for each option are listed below. -
At the very least, you must include the following inputs: 'orig', 'dest', and 'type'. Any other omitted inputs will be replaced with default values. If the 'route' input is omitted, it will be replaced with the recommended route from SimBrief database.
-
You must include
<script type="text/javascript" src="simbrief.apiv1.js"></script>in your html<head>tag, as it contains the necessary functions for the API to operate. -
The
<form>containing your Dispatch Options must have at least the following property:<form id="sbapiform">. -
Your form's submit button must have at least the following property:
<input type="button" onclick="simbriefsubmit('referral_page');" />, where "referral_page" is the link to the page you want the API to redirect to when the flight plan is ready. This is normally the output page on your website. -
The
"simbrief.apiv1.php"file will need to be included (<?php include 'simbrief.apiv1.php'; ?>) in your output page. It should reside in the same directory as the rest of your dispatch system, however if you absolutely need to have it in a different directory, you will need to modify the"var api_dir ="line in the"simbrief.apiv1.js"file to point to the proper location. -
Prior to using the API, you must obtain an API key and paste it into your
"simbrief.apiv1.php"file. Failure to do this will result in your flightplan requests being denied. API keys can be requested by contacting us. Please include information about your website and how you intend on using the API.
API ParametersRead the “API Parameters” section
The <input> names for each dispatch option are as follows:
| Dispatch Option | Input Name | Example Value 1, Example Value 2 |
|---|---|---|
| Airline | airline | ABC |
| Flight Number | fltnum | 1234 |
| Aircraft | type | B738 |
| Origin | orig | KORD |
| Destination | dest | KSFO |
| Date | date | 11JUL13 |
| Departure Time (Hour) | deph | 16 |
| Departure Time (Minute) | depm | 30 |
| Route | route | PLL GAROT OAL MOD4 |
| Scheduled Time (Hour) | steh | 4 |
| Scheduled Time (Minute) | stem | 30 |
| Aircraft Registration | reg | N123XX |
| Aircraft Fin Number | fin | 123 |
| Aircraft SELCAL | selcal | ABCD |
| ATC Callsign | callsign | ABC1234 |
| Passengers | pax | 100 |
| Alternate | altn | KLAX |
| Altitude | fl | 34000, FL340 |
| Captain's Name | cpt | JOHN DOE |
| Dispatcher's Name | dxname | JANE DOE |
| Pilot ID Number | pid | 12345 |
| Fuel Factor | fuelfactor | P00 |
| Manual ZFW | manualzfw | 40.1 |
| Extra Fuel | addedfuel | 0.5, 20 |
| Extra Fuel Units | addedfuel_units | wgt, min |
| Cont Fuel (% or minutes) | contpct | 0.05, 0.05/15 |
| Reserve Fuel (Minutes) | resvrule | 45 |
| Taxi Out (Minutes) | taxiout | 10 |
| Taxi In (Minutes) | taxiin | 4 |
| Cargo Weight | cargo | 5.0 |
| Departure Runway | origrwy | 06L |
| Arrival Runway | destrwy | 36R |
| Climb Profile | climb | 250/300/78 |
| Descent Profile | descent | 84/280/250 |
| Cruise Profile | cruise | LRC, CI |
| Cost Index | civalue | 25, AUTO |
| Aircraft Data***** | acdata | {"cat":"M","equip":"SDE3FGHIRWY","transponder":"S","pbn":"PBN/A1B1C1D1","extrarmk":"DAT/V RVR/250 RMK/EXAMPLE","maxpax":"146","oew":96.5,"mzfw":134.5,"mtow":169.8,"mlw":142.2,"maxfuel":42.6} |
| ETOPS Rule | etopsrule | 180, 207 |
| Number of Alternates | altn_count | 4 |
| Avoid Alternate Airports | altn_avoid | KJFK KPHL KBWI |
| Alternate #1 | altn_1_id | KJFK |
| Alternate #1 Runway | altn_1_rwy | 22R |
| Alternate #1 Routing | altn_1_route | SSOXS5 SSOXS DCT SEY PARCH2 |
| Alternate # 2-4 Ident | altn_#_id | KJFK |
| Alternate # 2-4 Runway | altn_#_rwy | 22R |
| Alternate # 2-4 Routing | altn_#_route | SSOXS5 SSOXS SEY PARCH2 |
| Custom Remarks | manualrmk | REMARK TEXT, FIRST REMARK\nSECOND REMARK |
| Static ID** | static_id | ABC_12345 |
OFP OptionsRead the “OFP Options” section
| Dispatch Option | Input Name | Example Value |
|---|---|---|
| Plan Format | planformat | LIDO |
| Units | units | LBS or KGS |
| Detailed Navlog | navlog | 1 or 0 (1 enables, 0 disables) |
| ETOPS Planning | etops | 1 or 0 (1 enables, 0 disables) |
| Plan Stepclimbs | stepclimbs | 1 or 0 (1 enables, 0 disables) |
| Runway Analysis | tlr | 1 or 0 (1 enables, 0 disables) |
| Include NOTAMs | notams | 1 or 0 (1 enables, 0 disables) |
| FIR NOTAMs | firnot | 1 or 0 (1 enables, 0 disables) |
| Flight Maps | maps | detail, simple, or none |
| Disable SIDs | omit_sids | 1 or 0 (1 omits them, 0 enables them) |
| Disable STARs | omit_stars | 1 or 0 (1 omits them, 0 enables them) |
| Auto-Insert SID/STARs | find_sidstar | R or C (Prefer RNAV or Non-RNAV) |
Note Regarding Static IDRead the “Note Regarding Static ID” section
This option allows you to set a reference static ID string that will remain the same, even if your user subsequently edits/regenerates their flight plan through the SimBrief website. The Static ID can be any combination of letters, numbers, and the underscore ( _ ) character.
When specified, the Static ID can be used to subsequently pull up the options or data for this API flight, even if the user has since edited the flight or generated a new flight plan on the SimBrief website.
To redirect a user to the SimBrief Options page for this API flight, the following link can be used:
https://www.simbrief.com/system/dispatch.php?editflight=last&static_id={your_static_id}
To pull up the latest XML data for this flight through the XML fetcher script, use the following link:
https://www.simbrief.com/api/xml.fetcher.php?userid={user_id}&static_id={your_static_id}
Note Regarding Aircraft DataRead the “Note Regarding Aircraft Data” section
Specific airframe data, such as aircraft weight limits and onboard equipment, can now be specified using the "acdata" parameter. This data must be passed as a JSON object, for example:
{
"cat": "M",
"equip": "SDE3FGHIRWY",
"transponder": "S",
"pbn": "PBN/A1B1C1D1",
"extrarmk": "DAT/V RVR/250 RMK/EXAMPLE",
"maxpax": "146",
"oew": 96.5,
"mzfw": 134.5,
"mtow": 169.8,
"mlw": 142.2,
"maxfuel": 42.6,
"hexcode": "123ABC",
"per": "D",
"paxwgt": 230
}
The following parameters can be specified: "cat" (aircraft weight category, i.e. L, M, H, or J), "equip" (the aircraft's onboard equipment string), "transponder" (the transponder type), "pbn" (performance based navigation string, must start with "PBN/..."), "extrarmk" (additional info to be included in Section 18 of the ICAO FPL string), "maxpax" (the maximum passenger count), "oew" (the operating empty weight), "mzfw" (the max zero fuel weight), "mtow" (the max takeoff weight), "mlw" (the max landing weight), "maxfuel" (the max fuel capacity), "hexcode" (the ICAO Mode-S Code), "per" (the ICAO performance category), and "paxwgt" (the average passenger weight to use, in pounds). All weights except the paxwgt value must be in thousands of pounds, but can be specified with up to 3 decimal places (in order to set precise values). Also note that for the "cat", "equip", and "transponder" options to work, all 3 must be specified. If one of the 3 parameters is missing, all 3 will be ignored.
Please ensure that your JSON string is properly encoded to be passed in a URL, otherwise it may not work correctly.
Using Custom User Airframes With the APIRead the “Using Custom User Airframes With the API” section
It's now possible to use a custom airframe that a user has saved to their SimBrief profile in an API request. To do so, simply have the user open the airframe for editing, and note the Internal ID number which appears near the top of the airframe options (it should look something like 123456_1582090020). Then, simply send this ID in your API request instead of the aircraft type code (for example, instead of sending B738, you would send 123456_1582090020).
When using this method, please note the following: Any changes that the airframe owner subsequently makes to this airframe will also immediately be reflected in any subsequent API flights you generate. Also, should the owner delete the airframe from their profile, any future API requests you make using this airframe’s Internal ID will fail with an Unknown Aircraft error.
Approximating Unsupported Aircraft TypesRead the “Approximating Unsupported Aircraft Types” section
Unsupported aircraft types can be approximated, or "faked", by adding additional parameters to the "acdata" JSON string explained above. Simply add any or all of these 3 additional parameters to the JSON string to simulate a different aircraft type: "icao" (the ICAO aircraft identifier, max 4 characters), "name" (the aircraft name, max 12 characters), and "engines" (the aircraft engine type, max 12 characters).
For example, a JSON string which would simulate a fictional Airbus A322 might look like this:
{
"icao": "A322",
"name": "A322-200",
"engines": "CFM56ZZZ/B",
"cat": "M",
"equip": "SDE3FGHIRWY",
"transponder": "S",
"pbn": "PBN/A1B1C1D1",
"maxpax": "205",
"oew": 106.5,
"mzfw": 154.5,
"mtow": 199.8,
"mlw": 182.2,
"maxfuel": 52.6
}
Note that limited support is given for this feature. Please try to base your faked aircraft on an aircraft which has similar weight/characteristics. Basing a faked aircraft on an aircraft which is much lighter/heavier can cause weird fuel figures as the system will have to extrapolate well outside the weights for which the original aircraft was programmed.