{"id":31556133,"url":"https://github.com/jongan69/ac-backend","last_synced_at":"2025-10-04T22:49:16.167Z","repository":{"id":308116034,"uuid":"1009862869","full_name":"jongan69/AC-Backend","owner":"jongan69","description":"AC-Backend API • Last updated: July 31, 2025 at 22:33 ET","archived":false,"fork":false,"pushed_at":"2025-08-04T06:51:02.000Z","size":2474,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-04T09:44:51.495Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://cd373195be65.ngrok-free.app/docs","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/jongan69.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,"zenodo":null}},"created_at":"2025-06-27T21:07:06.000Z","updated_at":"2025-08-04T06:51:06.000Z","dependencies_parsed_at":"2025-08-04T09:57:45.432Z","dependency_job_id":null,"html_url":"https://github.com/jongan69/AC-Backend","commit_stats":null,"previous_names":["jongan69/ac-backend"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jongan69/AC-Backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongan69%2FAC-Backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongan69%2FAC-Backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongan69%2FAC-Backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongan69%2FAC-Backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jongan69","download_url":"https://codeload.github.com/jongan69/AC-Backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongan69%2FAC-Backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278386116,"owners_count":25978109,"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","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-10-04T22:49:10.735Z","updated_at":"2025-10-04T22:49:16.161Z","avatar_url":"https://github.com/jongan69.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AC-Backend\n\n[![Refresh Webhook](https://github.com/jongan69/AC-Backend/actions/workflows/refresh-webhook.yml/badge.svg)](https://github.com/jongan69/AC-Backend/actions/workflows/refresh-webhook.yml)\n\n## Architecture Overview\n\n```mermaid\nflowchart TD\n    A[Client] --\u003e|/categorize| B[Transaction Categorization]\n    A --\u003e|/hotels/search| C[Hotel Search]\n    A --\u003e|/flights/search| D[Flight Search]\n    A --\u003e|/trip/plan| E[Trip Planning]\n    A --\u003e|/airbnbs/search| F[Airbnb Search]\n    A --\u003e|/airbnbs/details| G[Airbnb Details]\n    A --\u003e|/itinerary| H[Itinerary Suggestions]\n    B --\u003e|uses| B1[BankTransactionCategorizer]\n    C --\u003e|uses| C1[get_hotels]\n    D --\u003e|uses| D1[get_flights]\n    E --\u003e|uses| D1\n    E --\u003e|uses| C1\n    F --\u003e|uses| F1[pyairbnb.search_all]\n    G --\u003e|uses| G1[pyairbnb.get_details]\n    H --\u003e|uses| H1[Foursquare API]\n    H --\u003e|uses| H2[PredictHQ Events]\n```\n\n## Endpoint-Feature Mapping\n\n```mermaid\nflowchart TD\n    subgraph API Endpoints\n        A1[/categorize\\nPOST/] \n        A2[/hotels/search\\nPOST/]\n        A3[/flights/search\\nPOST/]\n        A4[/trip/plan\\nPOST/]\n        A5[/airbnbs/search\\nPOST/]\n        A6[/airbnbs/details\\nPOST/]\n        A7[/itinerary\\nGET/]\n        A8[/health\\nGET/]\n        A9[/\\nGET/]\n    end\n    subgraph Features\n        F1[Transaction Categorization]\n        F2[Hotel Search]\n        F3[Flight Search]\n        F4[Trip Planning]\n        F5[Airbnb Search]\n        F6[Airbnb Details]\n        F7[Itinerary Suggestions]\n        F8[Health Check]\n        F9[Root Welcome]\n    end\n    A1 --\u003e F1\n    A2 --\u003e F2\n    A3 --\u003e F3\n    A4 --\u003e F4\n    A5 --\u003e F5\n    A6 --\u003e F6\n    A7 --\u003e F7\n    A8 --\u003e F8\n    A9 --\u003e F9\n```\n\n## API Sequence Example\n\n```mermaid\nsequenceDiagram\n    participant Client\n    participant API as AC-Backend API\n    participant Hotels as Hotel Service\n    participant Flights as Flight Service\n    participant Airbnb as Airbnb Service\n    participant Foursquare as Foursquare API\n    participant PredictHQ as PredictHQ\n\n    Client-\u003e\u003eAPI: POST /categorize\n    API-\u003e\u003eAPI: Categorize transactions\n    API--\u003e\u003eClient: Categorized results\n\n    Client-\u003e\u003eAPI: POST /hotels/search\n    API-\u003e\u003eHotels: get_hotels\n    Hotels--\u003e\u003eAPI: Hotel results\n    API--\u003e\u003eClient: Hotel search results\n\n    Client-\u003e\u003eAPI: POST /flights/search\n    API-\u003e\u003eFlights: get_flights\n    Flights--\u003e\u003eAPI: Flight results\n    API--\u003e\u003eClient: Flight search results\n\n    Client-\u003e\u003eAPI: POST /trip/plan\n    API-\u003e\u003eFlights: get_flights (outbound/return)\n    API-\u003e\u003eHotels: get_hotels\n    Flights--\u003e\u003eAPI: Flight options\n    Hotels--\u003e\u003eAPI: Hotel options\n    API--\u003e\u003eClient: Best trip plan\n\n    Client-\u003e\u003eAPI: POST /airbnbs/search\n    API-\u003e\u003eAirbnb: pyairbnb.search_all\n    Airbnb--\u003e\u003eAPI: Airbnb results\n    API--\u003e\u003eClient: Airbnb search results\n\n    Client-\u003e\u003eAPI: POST /airbnbs/details\n    API-\u003e\u003eAirbnb: pyairbnb.get_details\n    Airbnb--\u003e\u003eAPI: Airbnb details\n    API--\u003e\u003eClient: Airbnb details\n\n    Client-\u003e\u003eAPI: GET /itinerary\n    API-\u003e\u003eFoursquare: Places API\n    API-\u003e\u003ePredictHQ: Events API\n    Foursquare--\u003e\u003eAPI: Places\n    PredictHQ--\u003e\u003eAPI: Events\n    API--\u003e\u003eClient: Grouped itinerary\n```\n\n---\n\n## API Endpoints\n\n### Root \u0026 Health\n\n#### `GET /`\n- **Description:** Root endpoint. Returns API status and documentation links.\n- **Response:**\n  ```json\n  { \"message\": \"Travel API is running\", \"docs\": \"/docs\", \"health\": \"/health\" }\n  ```\n\n#### `GET /health`\n- **Description:** Health check endpoint. Returns API status and current timestamp.\n- **Response:**\n  ```json\n  { \"status\": \"healthy\", \"timestamp\": \"2025-01-01T12:00:00\" }\n  ```\n\n---\n\n### Transaction Categorization\n\n#### `POST /categorize`\n- **Description:** Categorizes a list of bank transactions by description.\n- **Request Body:**\n  ```json\n  {\n    \"transactions\": [\n      { \"Description\": \"string\" }\n    ]\n  }\n  ```\n- **Response:**\n  ```json\n  {\n    \"results\": [\n      {\n        \"index\": 0,\n        \"Description\": \"string\",\n        \"Category\": \"string\",\n        \"Sub_Category\": \"string\",\n        \"Category_Confidence\": 0.95,\n        \"Sub_Category_Confidence\": 0.92\n      }\n    ]\n  }\n  ```\n\n---\n\n### Hotel Search\n\n#### `POST /hotels/search`\n- **Description:** Searches for hotels based on user criteria.\n- **Request Body:**\n  ```json\n  {\n    \"checkin_date\": \"YYYY-MM-DD\",\n    \"checkout_date\": \"YYYY-MM-DD\",\n    \"location\": \"string\",\n    \"adults\": 1,\n    \"children\": 0,\n    \"infants\": 0,\n    \"room_type\": \"standard\",\n    \"amenities\": [\"wifi\", \"breakfast\"],\n    \"fetch_mode\": \"fallback\",\n    \"limit\": 3,\n    \"debug\": false\n  }\n  ```\n- **Response:**\n  ```json\n  {\n    \"hotels\": [\n      {\n        \"name\": \"string\",\n        \"price\": 120.0,\n        \"rating\": 4.5,\n        \"url\": \"string\",\n        \"amenities\": [\"wifi\", \"breakfast\"]\n      }\n    ],\n    \"lowest_price\": 100.0,\n    \"current_price\": 120.0\n  }\n  ```\n\n---\n\n### Flight Search\n\n#### `POST /flights/search`\n- **Description:** Searches for flights (one-way or round-trip).\n- **Request Body:**\n  ```json\n  {\n    \"date\": \"YYYY-MM-DD\",\n    \"from_airport\": \"IATA\",\n    \"to_airport\": \"IATA\",\n    \"trip\": \"one-way\",\n    \"seat\": \"economy\",\n    \"adults\": 1,\n    \"children\": 0,\n    \"infants_in_seat\": 0,\n    \"infants_on_lap\": 0,\n    \"fetch_mode\": \"fallback\",\n    \"return_date\": \"YYYY-MM-DD\"\n  }\n  ```\n- **Response (one-way):**\n  ```json\n  {\n    \"flights\": [\n      {\n        \"name\": \"string\",\n        \"departure\": \"string\",\n        \"arrival\": \"string\",\n        \"arrival_time_ahead\": \"+1\",\n        \"duration\": \"4h 30m\",\n        \"stops\": 0,\n        \"delay\": \"string\",\n        \"price\": 350.0,\n        \"is_best\": true,\n        \"url\": \"string\"\n      }\n    ],\n    \"current_price\": \"350.0\"\n  }\n  ```\n- **Response (round-trip):**\n  ```json\n  {\n    \"outbound_flights\": [ ... ],\n    \"return_flights\": [ ... ],\n    \"current_price\": \"700.0\"\n  }\n  ```\n\n---\n\n### Trip Planning\n\n#### `POST /trip/plan`\n- **Description:** Plans a trip, including flights and hotels, and returns the best options and cost breakdown.\n- **Request Body:**\n  ```json\n  {\n    \"origin\": \"IATA\",\n    \"destination\": \"IATA\",\n    \"depart_date\": \"YYYY-MM-DD\",\n    \"return_date\": \"YYYY-MM-DD\",\n    \"adults\": 1,\n    \"children\": 0,\n    \"infants\": 0,\n    \"hotel_preferences\": {\n      \"star_rating\": 3,\n      \"max_price_per_night\": 150.0,\n      \"amenities\": [\"Free Wi-Fi\", \"Breakfast ($)\"]\n    },\n    \"room_type\": \"standard\",\n    \"amenities\": [\"wifi\", \"breakfast\"],\n    \"max_total_budget\": 3000.0\n  }\n  ```\n- **Response:**\n  ```json\n  {\n    \"best_outbound_flight\": { ... },\n    \"best_return_flight\": { ... },\n    \"best_hotel\": { ... },\n    \"total_estimated_cost\": 2500.0,\n    \"per_person_per_day\": 200.0,\n    \"breakdown\": {\n      \"flight\": 1500.0,\n      \"hotel\": 1000.0,\n      \"nights\": 5,\n      \"adults\": 2,\n      \"children\": 0\n    },\n    \"suggestions\": \"Consider adjusting your dates...\",\n    \"warning\": \"Partial results due to timeout.\"\n  }\n  ```\n\n---\n\n### Airbnb Search\n\n#### `POST /airbnbs/search`\n- **Description:** Searches for Airbnbs within a specified area and criteria.\n- **Request Body:**\n  ```json\n  {\n    \"check_in\": \"YYYY-MM-DD\",\n    \"check_out\": \"YYYY-MM-DD\",\n    \"ne_lat\": 35.0,\n    \"ne_long\": 139.0,\n    \"sw_lat\": 34.0,\n    \"sw_long\": 138.0,\n    \"zoom_value\": 2,\n    \"price_min\": 0,\n    \"price_max\": 0,\n    \"place_type\": \"Entire home/apt\",\n    \"amenities\": [1, 2],\n    \"currency\": \"USD\",\n    \"language\": \"en\",\n    \"proxy_url\": \"\",\n    \"limit\": 10\n  }\n  ```\n- **Response:**\n  ```json\n  {\n    \"airbnbs\": [\n      {\n        \"room_id\": 123456,\n        \"name\": \"string\",\n        \"title\": \"string\",\n        \"price\": 200.0,\n        \"per_night\": 100.0,\n        \"url\": \"string\",\n        \"rating\": 4.8,\n        \"review_count\": 50,\n        \"images\": [\"url1\", \"url2\"],\n        \"badges\": [\"Superhost\"],\n        \"latitude\": 35.0,\n        \"longitude\": 139.0\n      }\n    ],\n    \"lowest_price\": 100.0,\n    \"current_price\": 100.0\n  }\n  ```\n\n---\n\n### Airbnb Details\n\n#### `POST /airbnbs/details`\n- **Description:** Fetches detailed information for a specific Airbnb listing.\n- **Request Body:**\n  ```json\n  {\n    \"room_id\": 123456,\n    \"currency\": \"USD\",\n    \"language\": \"en\",\n    \"proxy_url\": \"\"\n  }\n  ```\n- **Response:**\n  ```json\n  {\n    \"name\": \"string\",\n    \"url\": \"string\",\n    \"rating\": 4.8,\n    \"amenities\": [\"Wi-Fi\", \"Kitchen\"],\n    \"images\": [\"url1\", \"url2\"],\n    \"review_count\": 50,\n    \"description\": \"string\",\n    \"location\": { ... },\n    \"host_name\": \"string\",\n    \"is_superhost\": true\n  }\n  ```\n\n---\n\n### Itinerary Suggestions\n\n#### `GET /itinerary`\n- **Description:** Returns grouped itinerary suggestions (places, events) for a location and date range.\n- **Query Parameters:**\n  - `lat`, `lng`, `start_date`, `end_date` (required)\n  - `radius`, `limit`, `query`, `open_now` (optional)\n- **Response:**\n  ```json\n  {\n    \"itinerary\": {\n      \"Food\": [ ... ],\n      \"Attractions\": [ ... ],\n      \"Events\": [ ... ]\n    }\n  }\n  ```\n\n---\n\n## NLTK Data Setup\n\nThis project uses NLTK resources (stopwords, wordnet, omw-1.4). Before running the API, ensure these are downloaded:\n\n```bash\npython scripts/download_nltk_data.py\n```\n\nIf you encounter errors about missing NLTK data, see the troubleshooting section in the code or run the above script again.\n\n---\n\n## Running the Server\n\n1. Install dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n2. Download NLTK data:\n   ```bash\n   python scripts/download_nltk_data.py\n   ```\n3. Start the server:\n   ```bash\n   uvicorn api:app --reload\n   ```\n4. Visit [http://localhost:8000/docs](http://localhost:8000/docs) for interactive API docs.\n\n---\n\n## Project Structure\n- `api.py`: Main FastAPI app and endpoints\n- `utils/`: Utility modules (data prep, model, etc.)\n- `scripts/`: Data processing and training scripts\n- `images/structure.png`: Project structure diagram\n\n---\n\n## License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjongan69%2Fac-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjongan69%2Fac-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjongan69%2Fac-backend/lists"}