Overview

The Gateway API provides the following services:

  • Get All Airports (GET /apiv1/airports)–Returns all of the airports in the database. This means that over 37,000 airports are returned!

  • Get a Single Airport (GET /apiv1/airport/[airport identifier])–Returns the airport with the specified airport code, plus all uploaded/accepted/approved (not declined) scenery information. The scenery objects contain metadata about each scenery pack, including the identifier. This allows you to do things like:

    • find the latest approved file,
    • find all files by a particular user (for that airport), or
    • find all files with a certain type (2D/3D) or specific scenery features.
  • Get Scenery (GET /apiv1/scenery/[scenery pack ID])–Returns the master zip blob and associated metadata for the specified scenery pack.

  • Put Scenery (PUT /apiv1/scenery)–Uploads the scenery pack you send to the server with the associated metadata.

  • Get Metadata Fields (GET /apiv1/metadata)–Returns the optional metadata fields we recognize in scenery pack uploads.

  • Get Stats (GET /apiv1/stats)–Returns metrics about the Gateway’s airport database.

  • Get Releases (GET /apiv1/releases)–Returns the dates at which we have pulled all airports in the Gateway database into various versions of X-Plane. You can use this, together with a Get Released Scenery Packs call, to determine if a given scenery pack was present in a particular version of X-Plane. There is also a readable table version of this data available at here.

  • Get Released Scenery Packs (GET /apiv1/release/[X-Plane version])–Returns a list of all Gateway scenery pack IDs that were present in the specified version of X-Plane.

Please note: There is currently no metering on the Gateway API, but we ask that you be considerate of our server load and avoid making unnecessary requests. (For instance, if you start making frequent requests to get all 34,000 airports in the database, we’ll have to cut you off!)

More Information and Sample Calls

Get All Airports

Returns an array of airport objects representing all known airports, with each airport containing the following fields:

JSON Field Data Type Description
AirportCode string Airport identifier code (most often an ICAO identifier)
AirportName string The full airport name (e.g., “Los Angeles Intl”)
AirportClass null Currently unused
Latitude number The latitude, in degrees, of the airport
Longitude number The longitude, in degrees, of the airport
Elevation number The elevation, in feet above mean sea level, of the airport
AcceptedSceneryCount number The number of scenery packs that have been accepted by the Gateway moderators
ApprovedSceneryCount number The number of scenery packs that have been approved by the Gateway moderators
RecommendedSceneryId number The scenery pack identifier for the recommended pack (zero if there is no recommended pack)
Status string “Scenery Submitted” or “Awaiting Scenery”
SceneryType number The number of scenery packs available for this airport that feature 3D scenery
SubmissionCount number The number of scenery packs that have been uploaded for this airport, minus any that have been marked as declined
checkedOutBy null or string Username of the Gateway artist who has checked out the airport (null if there is no check out in effect)
checkOutEndDate null or date string The date at which the current checkout will expire (or null if there is no checkout)
attributes string A comma-separated list of applicable airport attributes. Possible values include null, “3”, “4”, “3,4”, “4,3”, etc. (order doesn’t matter)
metadata null or object key/value of the metadata fields of the recommended scenery pack (or the most recent approved or submitted pack)

Sample “Get All Airports” Call

Result of GET http://gateway.x-plane.com/apiv1/airports (truncated):


Get a Single Airport

Returns an airport object which includes metadata about the airport (similar to the airport fields in the Get All Airports call), plus a list of all scenery packs uploaded for that airport.

The airport object has the following fields:

JSON Field Data Type Description
icao string Airport identifier code (most often an ICAO identifier)
airportName string The full airport name (e.g., “Los Angeles Intl”)
airportClass null Currently unused
latitude number The latitude, in degrees, of the airport
longitude number The longitude, in degrees, of the airport
elevation number The elevation, in feet above mean sea level, of the airport
acceptedSceneryCount number The number of scenery packs that have been accepted by the Gateway moderators
approvedSceneryCount number The number of scenery packs that have been approved by the Gateway moderators
recommendedSceneryId number The scenery pack identifier for the recommended pack (zero if there is no recommended pack)
scenery string An array of scenery pack objects (described below)
checkedOutBy null or string Username of the Gateway artist who has checked out the airport (null if there is no check out in effect)
checkOutEndDate null or date string The date at which the current checkout will expire (or null if there is no checkout)
attributes string A comma-separated list of applicable airport attributes. Possible values include null, “3”, “4”, “3,4”, “4,3”, etc. (order doesn’t matter)

Each of the scenery pack objects in the airport’s scenery field has the following fields:

JSON Field Data Type Description
sceneryId number The scenery pack’s unique identifier within the Gateway system (you can use this in a Get Scenery call to download the pack’s ZIP file)
parentId number If this scenery pack was created by modifying another, this will be the ID of the pack that this was created from
userId number The unique identifier of the artist that submitted this scenery pack
userName string The username of the artist that submitted this pack
dateUploaded date string The date at which the Gateway received the scenery pack submission
dateAccepted date string The date at which the Gateway moderators acknowledged the upload of the pack
dateApproved date string The date at which the Gateway moderators approved the scenery pack to potentially be included in a future version of X-Plane
dateDeclined date string The date at which the Gateway moderators marked the scenery pack as ineligible to be included in a future version of X-Plane
type string “3D” or “2D”
features string A comma-separated list of applicable scenery features. Possible values include null, “1”, “2”, “1,2”, “2,1”, etc. (order doesn’t matter)
artistComments string Comments from when the artist submitted the scenery pack
moderatorComments string Semicolon-separated list of all comments made by the moderator
Status string The scenery pack’s status; one of “Uploaded”, “Accepted”, “Approved”, “Declined”, or “Unknown”

Sample “Get a Single Airport” Call

Result of GET http://gateway.x-plane.com/apiv1/airport/KBOS:


Get Scenery

Very similar to the individual scenery pack objects in a Get a Single Airport call, with the notable addition of the masterZipBlob (the base64-encoded ZIP file containing the scenery pack).

JSON Field Data Type Description
sceneryId number The scenery pack’s unique identifier within the Gateway system (you can use this in a Get Scenery call to download the pack’s ZIP file)
parentId number If this scenery pack was created by modifying another, this will be the ID of the pack that this was created from
icao string Airport identifier code (most often an ICAO identifier)
aptName string The name of the airport, as set in its apt.dat file.
userName string The username of the artist that submitted this pack
dateUploaded date string The date at which the Gateway received the scenery pack submission
dateAccepted date string The date at which the Gateway moderators acknowledged the upload of the pack
dateApproved date string The date at which the Gateway moderators approved the scenery pack to potentially be included in a future version of X-Plane
dateDeclined date string The date at which the Gateway moderators marked the scenery pack as ineligible to be included in a future version of X-Plane
type string “3D” or “2D”
features string A comma-separated list of applicable scenery features. Possible values include null, “1”, “2”, “1,2”, “2,1”, etc. (order doesn’t matter)
artistComments string Comments from when the artist submitted the scenery pack
moderatorComments string Semicolon-separated list of all comments made by the moderator
masterZipBlob string The base64-encoded ZIP file that contains the scenery pack. Note that to get a usable ZIP file, you’ll need to base64-decode that string, then write the string to a .ZIP file.
additionalMetadata object Zero or more key-value pairs associating metadata fields with string values.

Sample “Get Scenery” Call

Result of GET http://gateway.x-plane.com/apiv1/scenery/1753:


Put Scenery

This is probably not the way you want to upload scenery. The built-in WED uploader provides validation of your scenery pack to ensure that no uploaded airport will break the X-Plane sim; if your scenery packs are found to be sidestepping this validation by accessing the Put Scenery API directly, the Gateway moderation staff may ban your account from future uploads.

NOTE: Since the Gateway API interface runs as a stateless service, it requires authentication information to be embedded with each “protected” request (currently limited to scenery upload requests).

Put Scenery also returns a scenery ID that can be saved, allowing the user direct access to the record stored on the server. The scenery record is not available with a Get Airport call until it is accepted by the moderator; however, Get Scenery using the scenery ID will always provide access to this file.

Sample “Put Scenery” Call

Data payload for a request to PUT http://gateway.x-plane.com/apiv1/scenery:


Get Metadata Fields

Response includes only one field, metadata_names, and array of strings. Individual scenery packs (available in a Get Scenery call) have values for zero or more of these metadata fields.

Sample “Get Metadata Fields” Call

Result of GET http://gateway.x-plane.com/apiv1/metadata:


Get Stats

Response includes the following fields:

JSON Field Data Type Description
airports number The number of distinct airports in the Gateway database. Note that this counts the number of airports, not scenery packs (there may be zero or more scenery packs submitted for a given airport).
userSceneryPacks number The number of scenery packs submitted for by Gateway users (that is, any user except our automated uploader, WEDbot). Note that this counts the number of scenery packs, not the number of airports (a given airport may have many scenery packs submitted for it).
sceneryPacks3D number The number of scenery packs submitted that include 3D objects. Note that this counts the number of scenery packs, not the number of airports with 3D scenery (a given airport may have many scenery packs submitted for it).
artists number The number of registered users on the Gateway

Sample “Get Stats” Call

Result of GET http://gateway.x-plane.com/apiv1/stats:


Get Releases

Response includes the following fields:

JSON Field Data Type Description
Version string An X-Plane version, like “10.30”
Date date string The date at which the Gateway took all recommended airports and exported them for inclusion in X-Plane

Sample “Get Releases” Call

Result of GET http://gateway.x-plane.com/apiv1/releases:


Get Released Scenery Packs

Response includes the following fields:

JSON Field Data Type Description
SceneryPacks array of numbers A list of all scenery packs (that is, their scenery pack ID) included in the release you specified

Sample “Released Scenery Packs” Call

Result of GET http://gateway.x-plane.com/apiv1/release/10.30:

Available Airport Attributes

We store a number of annotations about individual airports. These describe certain properties of the airports, and are available for search when searching “All Airports.” In addition, they are sometimes used internally by the X-Plane team to prioritize airports for future development.

An individual airport may have some, all, or none of the attributes we track.

The available attributes annotations are:

Available Scenery Features

We store a number of annotations about individual scenery packs. These describe certain properties of the scenery packs, and are available for search when searching “All Airports.” In addition, they are sometimes used internally by the X-Plane team to prioritize scenery packs for future development.

An individual scenery pack may have some, all, or none of the features we track.

The available feature annotations are: