Skip to content
BranchesTags

Repository files navigation

Skylite Navigation API

Skylite route planning and route parsing service.

Run

pip install -r requirements.txt
python -m navigation_service.server

Environment variables:

  • NAVDATA_DB_PATH: SQLite database path. Defaults to imported.db3 from this service directory.
  • NAV_API_HOST: bind host, defaults to 0.0.0.0.
  • NAV_API_PORT: bind port, defaults to 8027.
  • NAV_API_CORS_ORIGIN: CORS origin, defaults to *.
  • NAV_API_REDIS_URL: optional Redis URL for route-plan response caching.
  • NAV_API_REDIS_USERNAME: optional Redis ACL username. Overrides the username in NAV_API_REDIS_URL when set.
  • NAV_API_REDIS_PASSWORD: optional Redis password. Overrides the password in NAV_API_REDIS_URL when set.
  • NAV_API_ROUTE_CACHE_TTL_SECONDS: optional route-plan cache TTL, defaults to 604800.
  • NAV_API_REDIS_TIMEOUT_SECONDS: optional Redis socket timeout, defaults to 0.2.
  • NAV_API_PUBLIC_URL: public base URL used in generated chart styles/tilejson. Set this to https://navigation.api.skylitefly.com in production.
  • NAV_CHART_MBTILES_DIR: optional directory containing pre-rendered {ifr-high|ifr-low|vfr}.mbtiles files. Matching tiles are served from these files before falling back to dynamic generation.
  • NAV_CHARTS_SPRITE_DIR: optional directory containing sprite@2x.json and sprite@2x.png for chart clients that want sprite assets. If unset, the packaged chart sprite is served.
  • NAV_CHART_TILE_CACHE_SIZE: max in-memory chart tile entries. Defaults to 1024.
  • NAV_CHART_TILE_CACHE_BYTES: max in-memory chart tile bytes. Defaults to 268435456.

Docker

The published image:

crpi-a20te69e34l8yeun.ap-southeast-1.personal.cr.aliyuncs.com/skylite/skylite-navigation-api

The container listens on port 8000. The compose template maps it to host port 8027 and mounts navdata read-only:

docker compose up

API

All responses are JSON. GET query parameters are case-insensitive where they represent aviation identifiers. Response examples show representative data; large arrays such as waypoints, procedures, and segments are shortened.

Health

GET /health

Returns service health, database path, and the active navdata cycle name.

Response:

{
  "ok": true,
  "database": "C:/path/to/imported.db3",
  "cycle": "2604"
}

Navdata

GET /api/navdata/cycle

Returns AIRAC/navdata cycle metadata. Values depend on the mounted database:

{
  "name": "2604",
  "start_date": "16APR26",
  "end_date": "13MAY26"
}

Charts

Chart endpoints expose Mapbox-compatible vector chart base maps generated from the navdata database. Supported chart ids are ifr-high, ifr-low, and vfr.

  • GET /api/charts/{ifr-high|ifr-low|vfr}/{z}/{x}/{y}.pbf
  • GET /api/charts/{ifr-high|ifr-low|vfr}/tilejson.json
  • GET /api/charts/style/{ifr-high|ifr-low|vfr}.json
  • GET /api/charts/sprite/sprite@2x.{json|png}

Vector tile responses are cached by clients for seven days and also use the service's in-memory chart tile cache.

To pre-render MBTiles for deployment:

python scripts/render_charts_mbtiles.py --output-dir dist/charts --max-zoom 8

Use --bbox WEST SOUTH EAST NORTH to bake a focused region first. Mount the output directory at NAV_CHART_MBTILES_DIR; the API serves matching MBTiles records directly and dynamically renders only missing tiles.

Airports

GET /api/airports?query=ZGG&limit=20

Searches airports by ICAO or airport name. query is optional. limit defaults to 20 and is capped at 100.

Response:

{
  "airports": [
    {
      "type": "airport",
      "id": 16988,
      "ident": "ZGGG",
      "icao": "ZGGG",
      "name": "BAIYUN",
      "latitude": 23.39333333,
      "longitude": 113.30833333,
      "elevation_ft": 50,
      "transition_altitude_ft": 8860,
      "transition_level": 10800,
      "speed_limit_kt": 250,
      "speed_limit_altitude_ft": 10000
    }
  ]
}

GET /api/airports/{icao}

Returns airport details, runways, departure/arrival procedure options, and navdata cycle metadata.

Example:

curl "http://localhost:8027/api/airports/ZGGG"

Response:

{
  "airport": {
    "type": "airport",
    "id": 16988,
    "ident": "ZGGG",
    "icao": "ZGGG",
    "name": "BAIYUN",
    "latitude": 23.39333333,
    "longitude": 113.30833333,
    "elevation_ft": 50,
    "transition_altitude_ft": 8860,
    "transition_level": 10800,
    "speed_limit_kt": 250,
    "speed_limit_altitude_ft": 10000
  },
  "runways": [
    {
      "id": 42072,
      "ident": "01L",
      "heading": 13.914,
      "length_ft": 11155,
      "latitude": 23.38069167,
      "longitude": 113.27528889,
      "elevation_ft": 43
    }
  ],
  "procedures": {
    "departures": [
      {
        "id": "34102:RW01L",
        "terminal_id": 34102,
        "procedure": "AGVIL1",
        "name": "AGVIL1",
        "type": "SID",
        "transition": "RW01L",
        "runway": "01L",
        "waypoints": [
          {
            "type": "terminal",
            "id": 82181,
            "ident": "AGVIL",
            "name": "AGVIL",
            "latitude": 24.15305556,
            "longitude": 112.85527778,
            "track_code": "TF"
          }
        ],
        "connection_waypoint": {
          "type": "terminal",
          "id": 82181,
          "ident": "AGVIL",
          "name": "AGVIL",
          "latitude": 24.15305556,
          "longitude": 112.85527778,
          "track_code": "TF"
        }
      }
    ],
    "arrivals": []
  },
  "nav_cycle": {
    "name": "2604",
    "start_date": "16APR26",
    "end_date": "13MAY26"
  }
}

GET /api/airports/{icao}/runways

Returns runways for one airport.

Response:

{
  "airport": {
    "type": "airport",
    "id": 16988,
    "ident": "ZGGG",
    "icao": "ZGGG",
    "name": "BAIYUN",
    "latitude": 23.39333333,
    "longitude": 113.30833333,
    "elevation_ft": 50,
    "transition_altitude_ft": 8860,
    "transition_level": 10800,
    "speed_limit_kt": 250,
    "speed_limit_altitude_ft": 10000
  },
  "runways": [
    {
      "id": 42072,
      "ident": "01L",
      "heading": 13.914,
      "length_ft": 11155,
      "latitude": 23.38069167,
      "longitude": 113.27528889,
      "elevation_ft": 43
    }
  ]
}

GET /api/airports/{icao}/procedures?type=all

Returns procedure options for one airport.

type values:

  • all - default, returns departures and arrivals.
  • sid, departure, departures - returns departure procedures.
  • star, arrival, arrivals - returns arrival procedures.

Response for type=all:

{
  "airport": {
    "type": "airport",
    "id": 16988,
    "ident": "ZGGG",
    "icao": "ZGGG",
    "name": "BAIYUN",
    "latitude": 23.39333333,
    "longitude": 113.30833333,
    "elevation_ft": 50,
    "transition_altitude_ft": 8860,
    "transition_level": 10800,
    "speed_limit_kt": 250,
    "speed_limit_altitude_ft": 10000
  },
  "procedures": {
    "departures": [
      {
        "id": "34102:RW01L",
        "terminal_id": 34102,
        "procedure": "AGVIL1",
        "name": "AGVIL1",
        "type": "SID",
        "transition": "RW01L",
        "runway": "01L",
        "waypoints": [],
        "connection_waypoint": {
          "type": "terminal",
          "id": 82181,
          "ident": "AGVIL",
          "name": "AGVIL",
          "latitude": 24.15305556,
          "longitude": 112.85527778,
          "track_code": "TF"
        }
      }
    ],
    "arrivals": []
  }
}

Response for type=sid or type=star:

{
  "airport": {
    "type": "airport",
    "id": 16988,
    "ident": "ZGGG",
    "icao": "ZGGG",
    "name": "BAIYUN",
    "latitude": 23.39333333,
    "longitude": 113.30833333,
    "elevation_ft": 50,
    "transition_altitude_ft": 8860,
    "transition_level": 10800,
    "speed_limit_kt": 250,
    "speed_limit_altitude_ft": 10000
  },
  "type": "departure",
  "procedures": [
    {
      "id": "34102:RW01L",
      "terminal_id": 34102,
      "procedure": "AGVIL1",
      "name": "AGVIL1",
      "type": "SID",
      "transition": "RW01L",
      "runway": "01L",
      "waypoints": [],
      "connection_waypoint": {
        "type": "terminal",
        "id": 82181,
        "ident": "AGVIL",
        "name": "AGVIL",
        "latitude": 24.15305556,
        "longitude": 112.85527778,
        "track_code": "TF"
      }
    }
  ]
}

Points

GET /api/points/resolve?ident=BOVMA&near=ZGGG

Resolves an airport, waypoint, or navaid identifier. near is optional and can be used to choose the closest matching point when an identifier is duplicated.

Response:

{
  "point": {
    "type": "waypoint",
    "id": 82209,
    "ident": "BOVMA",
    "icao": null,
    "name": "BOVMA",
    "latitude": 23.82083333,
    "longitude": 114.28277778
  }
}

Routes

GET /api/routes/plan?origin=ZGGG&destination=ZSPD

Plans an airway route between two airports.

Optional query parameters:

  • departure: SID full name filter.
  • departure_transition: SID transition filter.
  • arrival: STAR full name filter.
  • arrival_transition: STAR transition filter.

Response:

{
  "origin": {
    "type": "airport",
    "id": 16988,
    "ident": "ZGGG",
    "icao": "ZGGG",
    "name": "BAIYUN",
    "latitude": 23.39333333,
    "longitude": 113.30833333,
    "elevation_ft": 50,
    "transition_altitude_ft": 8860,
    "transition_level": 10800,
    "speed_limit_kt": 250,
    "speed_limit_altitude_ft": 10000
  },
  "destination": {
    "type": "airport",
    "id": 17051,
    "ident": "ZSPD",
    "icao": "ZSPD",
    "name": "PUDONG",
    "latitude": 31.145,
    "longitude": 121.79333333,
    "elevation_ft": 12,
    "transition_altitude_ft": 9850,
    "transition_level": 11800,
    "speed_limit_kt": 250,
    "speed_limit_altitude_ft": 10000
  },
  "runways": {
    "origin": [],
    "destination": []
  },
  "nav_cycle": {
    "name": "2604",
    "start_date": "16APR26",
    "end_date": "13MAY26"
  },
  "route": {
    "string": "ZGGG SID BOVMA W41 OMDUP STAR ZSPD",
    "distance_nm": 649.1,
    "distance_km": 1202.1,
    "waypoint_count": 32,
    "waypoints": [],
    "airway_waypoints": [],
    "segments": [
      {
        "airway": "W41",
        "from": {
          "type": "waypoint",
          "id": 82209,
          "ident": "BOVMA",
          "name": "BOVMA",
          "latitude": 23.82083333,
          "longitude": 114.28277778
        },
        "to": {
          "type": "waypoint",
          "id": 82300,
          "ident": "OMDUP",
          "name": "OMDUP",
          "latitude": 24.6075,
          "longitude": 114.93027778
        }
      }
    ]
  },
  "selected_departure": null,
  "selected_arrival": null,
  "departure_options": [],
  "arrival_options": []
}

POST /api/routes/parse

Parses a route string, resolves waypoints, expands airway segments when possible, and returns distance and unresolved tokens.

Request body:

{
  "route": "ZGGG SID BOVMA W41 OMDUP G471 PLT A599 ELNEX G204 MULOV V73 SUPAR B221 AND STAR ZSPD",
  "origin": "ZGGG",
  "destination": "ZSPD"
}

Response:

{
  "route": "ZGGG SID BOVMA W41 OMDUP G471 PLT STAR ZSPD",
  "origin": "ZGGG",
  "destination": "ZSPD",
  "waypoint_count": 22,
  "distance_nm": 642.8,
  "distance_km": 1190.1,
  "waypoints": [
    {
      "type": "airport",
      "id": 16988,
      "ident": "ZGGG",
      "icao": "ZGGG",
      "name": "BAIYUN",
      "latitude": 23.39333333,
      "longitude": 113.30833333
    }
  ],
  "segments": [
    {
      "airway": "W41",
      "from": {
        "type": "waypoint",
        "id": 82209,
        "ident": "BOVMA",
        "name": "BOVMA",
        "latitude": 23.82083333,
        "longitude": 114.28277778
      },
      "to": {
        "type": "waypoint",
        "id": 82300,
        "ident": "OMDUP",
        "name": "OMDUP",
        "latitude": 24.6075,
        "longitude": 114.93027778
      },
      "waypoints": [
        {
          "type": "waypoint",
          "id": 82209,
          "ident": "BOVMA",
          "name": "BOVMA",
          "latitude": 23.82083333,
          "longitude": 114.28277778
        }
      ]
    }
  ],
  "unresolved": [
    {
      "token": "UNKNOWN",
      "reason": "identifier was not found"
    }
  ]
}

Errors

Validation and lookup failures return 400:

{
  "error": "Airport ZZZZ was not found in navdata."
}

Unknown paths return 404:

{
  "error": "Not found"
}

Unexpected failures return 500:

{
  "error": "Internal server error",
  "detail": "error details"
}

About

No description, website, or topics provided.

Resources

Readme
AGPL-3.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages