{"id":24136238,"url":"https://github.com/catlikeflyer/airfacts","last_synced_at":"2026-04-11T19:03:10.548Z","repository":{"id":270299147,"uuid":"909887544","full_name":"catlikeflyer/airfacts","owner":"catlikeflyer","description":"FastAPI connected to a Neo4j database to retrieve airplane, airport and air route data","archived":false,"fork":false,"pushed_at":"2025-01-19T04:41:31.000Z","size":2047,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-19T05:26:04.646Z","etag":null,"topics":["api-rest","cypher","database","docker","fastapi","neo4j"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/catlikeflyer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-30T01:33:35.000Z","updated_at":"2025-01-19T04:41:33.000Z","dependencies_parsed_at":"2024-12-30T06:23:38.147Z","dependency_job_id":"cf369f10-831f-464c-b580-0374d583466b","html_url":"https://github.com/catlikeflyer/airfacts","commit_stats":null,"previous_names":["catlikeflyer/airfacts"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catlikeflyer%2Fairfacts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catlikeflyer%2Fairfacts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catlikeflyer%2Fairfacts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catlikeflyer%2Fairfacts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catlikeflyer","download_url":"https://codeload.github.com/catlikeflyer/airfacts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241361447,"owners_count":19950382,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-rest","cypher","database","docker","fastapi","neo4j"],"created_at":"2025-01-12T02:46:47.540Z","updated_at":"2025-12-30T21:38:16.108Z","avatar_url":"https://github.com/catlikeflyer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Airfacts\n\nNeo4j database that provides information about airports, airlines, and flight routes worldwide.\n\n## Background\n\nAs an aviation enthusiast, I wanted to create a project that provides easy access to aviation data. While there are existing APIs, many are paid services. This project uses FastAPI and Neo4j to offer a free alternative for retrieving information about airports, airlines, and routes.\n\n## Features\n\n- 🛫 **Airports**: Search airports by IATA code, city, or country\n- ✈️ **Airlines**: Get airline information by IATA code or country\n- 🗺️ **Routes**: Find flight routes between airports\n- 📊 **Real-time Data**: Data fetched from OpenFlights\n- 🚀 **Fast API**: Built with FastAPI for high performance\n- 📝 **Auto Documentation**: Interactive API docs at `/docs`\n- 🎨 **Dashboard**: Interactive Streamlit dashboard for data visualization\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.8 or higher\n- Docker (for Neo4j database)\n- Git\n\n### Easy Setup (macOS/Linux)\n\n**Option 1: Using the automated script**\n\n```bash\nchmod +x start.sh\n./start.sh\n```\n\n**Option 2: Using Make commands**\n\n```bash\nmake all      # Complete setup\nmake start    # Start the API server\n```\n\nRun `make help` to see all available commands.\n\nThese automated tools will:\n\n- Create a virtual environment\n- Install all dependencies\n- Start Neo4j in Docker\n- Optionally load data from OpenFlights\n- Start the API server\n\n### Manual Installation\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/catlikeflyer/airfacts.git\n   cd airfacts\n   ```\n\n2. **Create a virtual environment**\n\n   ```bash\n   python3 -m venv .venv\n   source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n   ```\n\n3. **Install dependencies**\n\n   ```bash\n   pip install -r requirements-minimal.txt\n   ```\n\n4. **Set up Neo4j Database**\n\n   Choose one of the following options:\n\n   **Option A: Using Docker (Recommended)**\n\n   ```bash\n   docker run --name neo4j \\\n     -p 7474:7474 -p 7687:7687 \\\n     -d \\\n     -v $HOME/neo4j/data:/data \\\n     -v $HOME/neo4j/logs:/logs \\\n     -v $HOME/neo4j/import:/var/lib/neo4j/import \\\n     -v $HOME/neo4j/plugins:/plugins \\\n     --env NEO4J_AUTH=neo4j/airfacts-pw \\\n     neo4j:latest\n   ```\n\n   **Option B: Using Neo4j Desktop**\n\n   - Download and install [Neo4j Desktop](https://neo4j.com/download/)\n   - Create a new database\n   - Set username to `neo4j` and password to `airfacts-pw`\n   - Start the database on `bolt://localhost:7687`\n\n5. **Load data into Neo4j**\n\n   ```bash\n   cd neo4j\n   python3 loader.py\n   ```\n\n   This will fetch data from OpenFlights and populate your Neo4j database. This may take a few minutes.\n\n6. **Run the API**\n\n   ```bash\n   cd ../api\n   uvicorn main:app --reload --host 0.0.0.0 --port 8000\n   ```\n\n7. **Access the API**\n\n   - API: http://localhost:8000\n   - Interactive Docs: http://localhost:8000/docs\n   - Neo4j Browser: http://localhost:7474\n\n8. **(Optional) Run the Dashboard**\n   ```bash\n   cd ../dashboard\n   pip install -r requirements.txt\n   streamlit run app.py\n   ```\n   - Dashboard: http://localhost:8501\n\n## Dashboard Features\n\n### Phase 1 (MVP) ✅ Complete\n\n- ✅ Airport search and details\n- ✅ Simple route finder between two airports\n- ✅ Basic statistics (total airports, airlines, routes)\n- ✅ Map with all airports plotted\n\n### Phase 2 🚧 Work in Progress\n\n- ✅ Airline route networks on map\n- ✅ Top N airports/airlines charts\n- 🚧 Distance-based filtering\n- 🚧 Graph visualization\n\n### Phase 3 📋 Planned\n\n- 📋 Shortest path algorithm\n- 📋 Advanced analytics\n- 📋 Export functionality\n- 📋 Real-time filtering\n\n## Usage Examples\n\n### Get all airports (with pagination)\n\n```bash\ncurl \"http://localhost:8000/api/airports/?limit=10\u0026skip=0\"\n```\n\n### Get a specific airport by IATA code\n\n```bash\ncurl \"http://localhost:8000/api/airports/JFK\"\n```\n\n### Get airports in a specific country\n\n```bash\ncurl \"http://localhost:8000/api/airports/country/United%20States\"\n```\n\n### Get all airlines\n\n```bash\ncurl \"http://localhost:8000/api/airlines/?limit=10\"\n```\n\n### Get routes from an airport\n\n```bash\ncurl \"http://localhost:8000/api/routes/source/JFK\"\n```\n\n### Get routes between two airports\n\n```bash\ncurl \"http://localhost:8000/api/routes/source/JFK/destination/LAX\"\n```\n\n## API Endpoints\n\n### Airports\n\n- `GET /api/airports/` - Get all airports (paginated)\n- `GET /api/airports/{iata}` - Get airport by IATA code\n- `GET /api/airports/country/{country}` - Get airports by country\n\n### Airlines\n\n- `GET /api/airlines/` - Get all airlines (paginated)\n- `GET /api/airlines/{iata}` - Get airline by IATA code\n- `GET /api/airlines/country/{country}` - Get airlines by country\n\n### Routes\n\n- `GET /api/routes/source/{iata}` - Get routes from an airport\n- `GET /api/routes/destination/{iata}` - Get routes to an airport\n- `GET /api/routes/source/{source}/destination/{dest}` - Get routes between two airports\n- `GET /api/routes/airline/{iata}` - Get all routes for an airline\n\nFor detailed schema information, see [API_SCHEMAS.md](API_SCHEMAS.md)\n\n## Database Structure\n\nThe project uses a Neo4j database. To run the database, you need to have Docker installed.\n\n### Database Schema\n\nThe data is fetched directly from [OpenFlights](https://openflights.org/data.html) and stored in a Neo4j database. The database is structured as follows:\n\n### Nodes\n\n- Airport Node: Represents an airport and contains attributes such as:\n  - AirportID\n  - Name\n  - City\n  - Country\n  - IATA\n  - ICAO\n  - Latitude\n  - Longitude\n  - Altitude\n  - Timezone\n  - DST\n  - Tz database time zone\n  - Type\n  - Source\n- Each airport node will be uniquely identified by the IATA code (e.g., \"JFK\", \"LAX\").\n- Airline Node: Represents an airline and contains attributes such as:\n  - AirlineID\n  - Name\n  - Alias\n  - ICAO\n  - Callsign\n  - Country\n  - Active\n- Each airline node will be uniquely identified by the IATA code of the airline (e.g., \"AA\" for American Airlines).\n\n### Relationships (Edges)\n\n- ROUTE Relationship: Represents a flight route between two airports and contains properties such as:\n  - Stops: Number of stops on the route (0 for direct flights)\n  - Equipment: The aircraft type used on the route\n  - Codeshare: Indicates if it's a codeshare route (e.g., \"Y\" or null)\n  - Airline: The airline that operates the route (linked to the Airline node)\n  - Example: A ROUTE relationship connects a source airport (e.g., JFK) to a destination airport (e.g., LAX), and the relationship contains the airline's name, number of stops, and aircraft used.\n- OPERATES_AT Relationship (Optional): Represents the relationship between an Airline and an Airport showing that the airline operates at the airport. This is not strictly necessary but can be useful for certain queries.\n  - Example: An Airline (e.g., AA) operates at a specific Airport (e.g., JFK).\n\n## Development\n\n### Project Structure\n\n```\nairfacts/\n├── api/                      # FastAPI application\n│   ├── main.py              # Main application entry point\n│   ├── database.py          # Neo4j connection\n│   ├── schemas.py           # Pydantic models\n│   └── routers/             # API route handlers\n│       ├── airports.py\n│       ├── airlines.py\n│       └── routes.py\n├── neo4j/                   # Database related files\n│   ├── loader.py            # Data loading script\n│   ├── Dockerfile           # Neo4j container config\n│   └── cypher/              # Cypher query files\n│       ├── load_airport.cypher\n│       ├── load_airline.cypher\n│       └── load_route.cypher\n├── requirements-minimal.txt  # Python dependencies\n└── README.md                # This file\n```\n\n### Running in Development Mode\n\nStart the API with auto-reload on code changes:\n\n```bash\ncd api\nuvicorn main:app --reload --host 0.0.0.0 --port 8000\n```\n\n### Environment Variables\n\nThe application uses environment variables for configuration. You can set them using a `.env` file in the project root.\n\n**Create a `.env` file:**\n\n```bash\ncp .env.example .env\n```\n\n**Edit `.env` with your configuration:**\n\n```bash\nNEO4J_URI=bolt://localhost:7687\nNEO4J_USERNAME=neo4j\nNEO4J_PASSWORD=airfacts-pw\n```\n\nAlternatively, you can export environment variables in your shell:\n\n```bash\nexport NEO4J_URI=\"bolt://localhost:7687\"\nexport NEO4J_USERNAME=\"neo4j\"\nexport NEO4J_PASSWORD=\"airfacts-pw\"\n```\n\nThe application automatically loads variables from `.env` using python-dotenv.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Troubleshooting\n\nHaving issues? Check out the [Troubleshooting Guide](TROUBLESHOOTING.md) for common problems and solutions.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Data Source\n\nThe data is retrieved from the following source:\n\n- [OpenFlights](https://openflights.org/data.html) - Airport, airline, and route data\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatlikeflyer%2Fairfacts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatlikeflyer%2Fairfacts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatlikeflyer%2Fairfacts/lists"}