1. /SimBrief
  2. /Using the API

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:

  1. 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.

  2. 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.

  3. 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.

  4. The <form> containing your Dispatch Options must have at least the following property: <form id="sbapiform">.

  5. 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.

  6. 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.

  7. 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 OptionInput NameExample Value 1, Example Value 2
Flight Numberfltnum1234
Departure Time (Hour)deph16
Departure Time (Minute)depm30
Scheduled Time (Hour)steh4
Scheduled Time (Minute)stem30
Aircraft RegistrationregN123XX
Aircraft Fin Numberfin123
Aircraft SELCALselcalABCD
ATC CallsigncallsignABC1234
Altitudefl34000, FL340
Captain's NamecptJOHN DOE
Dispatcher's NamedxnameJANE DOE
Pilot ID Numberpid12345
Fuel FactorfuelfactorP00
Manual ZFWmanualzfw40.1
Extra Fueladdedfuel0.5, 20
Extra Fuel Unitsaddedfuel_unitswgt, min
Cont Fuel (% or minutes)contpct0.05, 0.05/15
Reserve Fuel (Minutes)resvrule45
Taxi Out (Minutes)taxiout10
Taxi In (Minutes)taxiin4
Cargo Weightcargo5.0
Departure Runwayorigrwy06L
Arrival Runwaydestrwy36R
Climb Profileclimb250/300/78
Descent Profiledescent84/280/250
Cruise ProfilecruiseLRC, CI
Cost Indexcivalue25, 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 Ruleetopsrule180, 207
Number of Alternatesaltn_count4
Avoid Alternate Airportsaltn_avoidKJFK KPHL KBWI
Alternate #1altn_1_idKJFK
Alternate #1 Runwayaltn_1_rwy22R
Alternate #1 Routingaltn_1_routeSSOXS5 SSOXS DCT SEY PARCH2
Alternate # 2-4 Identaltn_#_idKJFK
Alternate # 2-4 Runwayaltn_#_rwy22R
Alternate # 2-4 Routingaltn_#_routeSSOXS5 SSOXS SEY PARCH2
Static ID**static_idABC_12345

OFP OptionsRead the “OFP Options” section

Dispatch OptionInput NameExample Value
Plan FormatplanformatLIDO
UnitsunitsLBS or KGS
Detailed Navlognavlog1 or 0 (1 enables, 0 disables)
ETOPS Planningetops1 or 0 (1 enables, 0 disables)
Plan Stepclimbsstepclimbs1 or 0 (1 enables, 0 disables)
Runway Analysistlr1 or 0 (1 enables, 0 disables)
Include NOTAMsnotams1 or 0 (1 enables, 0 disables)
FIR NOTAMsfirnot1 or 0 (1 enables, 0 disables)
Flight Mapsmapsdetail, simple, or none
Disable SIDsomit_sids1 or 0 (1 omits them, 0 enables them)
Disable STARsomit_stars1 or 0 (1 omits them, 0 enables them)
Auto-Insert SID/STARsfind_sidstarR 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:{your_static_id}

To pull up the latest XML data for this flight through the XML fetcher script, use the following link:{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.