X-Plane Scenery Gateway API Documentation
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: