{
 "openapi": "3.1.0",
 "info": {
  "title": "Navo Flight Schedules API",
  "version": "0.1.0",
  "description": "Scheduled cargo (freighter) and passenger flights by route, flight number and airport board. Data from official airport flight information, refreshed every 3 hours, 7 days ahead. Beta: coverage grows weekly, see /api/v1/coverage."
 },
 "servers": [
  {
   "url": "https://flight.navo24.com"
  }
 ],
 "paths": {
  "/api/v1/flights": {
   "get": {
    "summary": "Flights by route",
    "operationId": "flightsByRoute",
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "required": true,
      "description": "Origin IATA airport",
      "schema": {
       "type": "string"
      },
      "example": "HKG"
     },
     {
      "name": "to",
      "in": "query",
      "required": true,
      "description": "Destination IATA airport",
      "schema": {
       "type": "string"
      },
      "example": "FRA"
     },
     {
      "name": "date",
      "in": "query",
      "required": false,
      "description": "First day, YYYY-MM-DD (default today)",
      "schema": {
       "type": "string"
      },
      "example": "2026-10-30"
     },
     {
      "name": "days",
      "in": "query",
      "required": false,
      "description": "Window in days, 1-14 (default 7)",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cargo",
      "in": "query",
      "required": false,
      "description": "1 = freighters only",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "airline",
      "in": "query",
      "required": false,
      "description": "ICAO airline code or flight prefix, e.g. CPA or LH",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "flight_no": {
              "type": "string",
              "example": "LH8461"
             },
             "airline": {
              "type": "object",
              "properties": {
               "icao": {
                "type": "string"
               },
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               }
              }
             },
             "codeshares": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "date": {
              "type": "string",
              "format": "date",
              "description": "Local date at the reporting station"
             },
             "time_local": {
              "type": "string",
              "example": "02:05",
              "description": "Scheduled time, local at the station"
             },
             "tz": {
              "type": "string"
             },
             "departure_utc": {
              "type": "string"
             },
             "arrival_utc": {
              "type": "string"
             },
             "origin": {
              "type": "object",
              "properties": {
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               },
               "city": {
                "type": "string"
               },
               "country": {
                "type": "string"
               },
               "lat": {
                "type": "number"
               },
               "lon": {
                "type": "number"
               },
               "tz": {
                "type": "string"
               }
              }
             },
             "destination": {
              "type": "object",
              "properties": {
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               },
               "city": {
                "type": "string"
               },
               "country": {
                "type": "string"
               },
               "lat": {
                "type": "number"
               },
               "lon": {
                "type": "number"
               },
               "tz": {
                "type": "string"
               }
              }
             },
             "via": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "iata": {
                 "type": "string"
                },
                "name": {
                 "type": "string"
                },
                "city": {
                 "type": "string"
                },
                "country": {
                 "type": "string"
                },
                "lat": {
                 "type": "number"
                },
                "lon": {
                 "type": "number"
                },
                "tz": {
                 "type": "string"
                }
               }
              }
             },
             "stops": {
              "type": "integer"
             },
             "board": {
              "type": "string",
              "enum": [
               "dep",
               "arr"
              ]
             },
             "station": {
              "type": "string",
              "description": "Airport whose board reported the flight"
             },
             "cargo": {
              "type": "boolean",
              "description": "true = freighter / cargo-only flight"
             },
             "status": {
              "type": "string",
              "example": "Dep 00:31"
             },
             "terminal": {
              "type": "string",
              "nullable": true
             },
             "gate": {
              "type": "string",
              "nullable": true
             },
             "source": {
              "type": "string",
              "example": "hkg"
             },
             "updated_at": {
              "type": "string"
             }
            }
           }
          },
          "meta": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad input",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found / not covered",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Rate or demo limit",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/flights/{flight_no}": {
   "get": {
    "summary": "One flight number",
    "operationId": "flightByNumber",
    "parameters": [
     {
      "name": "flight_no",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "LH8461"
     },
     {
      "name": "date",
      "in": "query",
      "required": false,
      "description": "Local date, YYYY-MM-DD (optional)",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "flight_no": {
              "type": "string",
              "example": "LH8461"
             },
             "airline": {
              "type": "object",
              "properties": {
               "icao": {
                "type": "string"
               },
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               }
              }
             },
             "codeshares": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "date": {
              "type": "string",
              "format": "date",
              "description": "Local date at the reporting station"
             },
             "time_local": {
              "type": "string",
              "example": "02:05",
              "description": "Scheduled time, local at the station"
             },
             "tz": {
              "type": "string"
             },
             "departure_utc": {
              "type": "string"
             },
             "arrival_utc": {
              "type": "string"
             },
             "origin": {
              "type": "object",
              "properties": {
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               },
               "city": {
                "type": "string"
               },
               "country": {
                "type": "string"
               },
               "lat": {
                "type": "number"
               },
               "lon": {
                "type": "number"
               },
               "tz": {
                "type": "string"
               }
              }
             },
             "destination": {
              "type": "object",
              "properties": {
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               },
               "city": {
                "type": "string"
               },
               "country": {
                "type": "string"
               },
               "lat": {
                "type": "number"
               },
               "lon": {
                "type": "number"
               },
               "tz": {
                "type": "string"
               }
              }
             },
             "via": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "iata": {
                 "type": "string"
                },
                "name": {
                 "type": "string"
                },
                "city": {
                 "type": "string"
                },
                "country": {
                 "type": "string"
                },
                "lat": {
                 "type": "number"
                },
                "lon": {
                 "type": "number"
                },
                "tz": {
                 "type": "string"
                }
               }
              }
             },
             "stops": {
              "type": "integer"
             },
             "board": {
              "type": "string",
              "enum": [
               "dep",
               "arr"
              ]
             },
             "station": {
              "type": "string",
              "description": "Airport whose board reported the flight"
             },
             "cargo": {
              "type": "boolean",
              "description": "true = freighter / cargo-only flight"
             },
             "status": {
              "type": "string",
              "example": "Dep 00:31"
             },
             "terminal": {
              "type": "string",
              "nullable": true
             },
             "gate": {
              "type": "string",
              "nullable": true
             },
             "source": {
              "type": "string",
              "example": "hkg"
             },
             "updated_at": {
              "type": "string"
             }
            }
           }
          },
          "meta": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad input",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found / not covered",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Rate or demo limit",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/airports/{iata}/departures": {
   "get": {
    "summary": "Departure board",
    "operationId": "departures",
    "parameters": [
     {
      "name": "iata",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "HKG"
     },
     {
      "name": "date",
      "in": "query",
      "required": false,
      "description": "Local date",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "cargo",
      "in": "query",
      "required": false,
      "description": "1 = freighters only",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "flight_no": {
              "type": "string",
              "example": "LH8461"
             },
             "airline": {
              "type": "object",
              "properties": {
               "icao": {
                "type": "string"
               },
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               }
              }
             },
             "codeshares": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "date": {
              "type": "string",
              "format": "date",
              "description": "Local date at the reporting station"
             },
             "time_local": {
              "type": "string",
              "example": "02:05",
              "description": "Scheduled time, local at the station"
             },
             "tz": {
              "type": "string"
             },
             "departure_utc": {
              "type": "string"
             },
             "arrival_utc": {
              "type": "string"
             },
             "origin": {
              "type": "object",
              "properties": {
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               },
               "city": {
                "type": "string"
               },
               "country": {
                "type": "string"
               },
               "lat": {
                "type": "number"
               },
               "lon": {
                "type": "number"
               },
               "tz": {
                "type": "string"
               }
              }
             },
             "destination": {
              "type": "object",
              "properties": {
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               },
               "city": {
                "type": "string"
               },
               "country": {
                "type": "string"
               },
               "lat": {
                "type": "number"
               },
               "lon": {
                "type": "number"
               },
               "tz": {
                "type": "string"
               }
              }
             },
             "via": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "iata": {
                 "type": "string"
                },
                "name": {
                 "type": "string"
                },
                "city": {
                 "type": "string"
                },
                "country": {
                 "type": "string"
                },
                "lat": {
                 "type": "number"
                },
                "lon": {
                 "type": "number"
                },
                "tz": {
                 "type": "string"
                }
               }
              }
             },
             "stops": {
              "type": "integer"
             },
             "board": {
              "type": "string",
              "enum": [
               "dep",
               "arr"
              ]
             },
             "station": {
              "type": "string",
              "description": "Airport whose board reported the flight"
             },
             "cargo": {
              "type": "boolean",
              "description": "true = freighter / cargo-only flight"
             },
             "status": {
              "type": "string",
              "example": "Dep 00:31"
             },
             "terminal": {
              "type": "string",
              "nullable": true
             },
             "gate": {
              "type": "string",
              "nullable": true
             },
             "source": {
              "type": "string",
              "example": "hkg"
             },
             "updated_at": {
              "type": "string"
             }
            }
           }
          },
          "meta": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad input",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found / not covered",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Rate or demo limit",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/airports/{iata}/arrivals": {
   "get": {
    "summary": "Arrival board",
    "operationId": "arrivals",
    "parameters": [
     {
      "name": "iata",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "HKG"
     },
     {
      "name": "date",
      "in": "query",
      "required": false,
      "description": "Local date",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "cargo",
      "in": "query",
      "required": false,
      "description": "1 = freighters only",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "flight_no": {
              "type": "string",
              "example": "LH8461"
             },
             "airline": {
              "type": "object",
              "properties": {
               "icao": {
                "type": "string"
               },
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               }
              }
             },
             "codeshares": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "date": {
              "type": "string",
              "format": "date",
              "description": "Local date at the reporting station"
             },
             "time_local": {
              "type": "string",
              "example": "02:05",
              "description": "Scheduled time, local at the station"
             },
             "tz": {
              "type": "string"
             },
             "departure_utc": {
              "type": "string"
             },
             "arrival_utc": {
              "type": "string"
             },
             "origin": {
              "type": "object",
              "properties": {
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               },
               "city": {
                "type": "string"
               },
               "country": {
                "type": "string"
               },
               "lat": {
                "type": "number"
               },
               "lon": {
                "type": "number"
               },
               "tz": {
                "type": "string"
               }
              }
             },
             "destination": {
              "type": "object",
              "properties": {
               "iata": {
                "type": "string"
               },
               "name": {
                "type": "string"
               },
               "city": {
                "type": "string"
               },
               "country": {
                "type": "string"
               },
               "lat": {
                "type": "number"
               },
               "lon": {
                "type": "number"
               },
               "tz": {
                "type": "string"
               }
              }
             },
             "via": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "iata": {
                 "type": "string"
                },
                "name": {
                 "type": "string"
                },
                "city": {
                 "type": "string"
                },
                "country": {
                 "type": "string"
                },
                "lat": {
                 "type": "number"
                },
                "lon": {
                 "type": "number"
                },
                "tz": {
                 "type": "string"
                }
               }
              }
             },
             "stops": {
              "type": "integer"
             },
             "board": {
              "type": "string",
              "enum": [
               "dep",
               "arr"
              ]
             },
             "station": {
              "type": "string",
              "description": "Airport whose board reported the flight"
             },
             "cargo": {
              "type": "boolean",
              "description": "true = freighter / cargo-only flight"
             },
             "status": {
              "type": "string",
              "example": "Dep 00:31"
             },
             "terminal": {
              "type": "string",
              "nullable": true
             },
             "gate": {
              "type": "string",
              "nullable": true
             },
             "source": {
              "type": "string",
              "example": "hkg"
             },
             "updated_at": {
              "type": "string"
             }
            }
           }
          },
          "meta": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad input",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found / not covered",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Rate or demo limit",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/airports": {
   "get": {
    "summary": "Airport search (autocomplete)",
    "operationId": "airports",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": "",
      "description": "IATA code, city or name",
      "schema": {
       "type": "string"
      },
      "example": "frankfurt"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "iata": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "city": {
              "type": "string"
             },
             "country": {
              "type": "string"
             },
             "lat": {
              "type": "number"
             },
             "lon": {
              "type": "number"
             },
             "tz": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/airlines": {
   "get": {
    "summary": "Airlines in coverage",
    "operationId": "airlines",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Name or code",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/coverage": {
   "get": {
    "summary": "Connectors, airports, airlines, dates in the database",
    "operationId": "coverage",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 }
}