{"id":18153278,"url":"https://github.com/alfex4936/k-festia","last_synced_at":"2026-04-12T12:41:52.030Z","repository":{"id":259721495,"uuid":"864511620","full_name":"Alfex4936/K-Festia","owner":"Alfex4936","description":"외국인을 위한 대한민국 전국 축제 (Korean festival information for foreigners)","archived":false,"fork":false,"pushed_at":"2025-05-20T13:43:25.000Z","size":1874,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-20T14:45:30.698Z","etag":null,"topics":["festival","graphql","korea","lucene","south-korea","spring","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","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/Alfex4936.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-09-28T12:18:10.000Z","updated_at":"2025-05-20T13:43:30.000Z","dependencies_parsed_at":"2024-10-27T15:36:09.987Z","dependency_job_id":"d00901f7-1fb8-4660-9c8f-59fbb341f8b7","html_url":"https://github.com/Alfex4936/K-Festia","commit_stats":null,"previous_names":["alfex4936/k-festia"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Alfex4936/K-Festia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfex4936%2FK-Festia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfex4936%2FK-Festia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfex4936%2FK-Festia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfex4936%2FK-Festia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Alfex4936","download_url":"https://codeload.github.com/Alfex4936/K-Festia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfex4936%2FK-Festia/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262240095,"owners_count":23280453,"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":["festival","graphql","korea","lucene","south-korea","spring","spring-boot"],"created_at":"2024-11-02T03:06:13.597Z","updated_at":"2026-04-12T12:41:51.994Z","avatar_url":"https://github.com/Alfex4936.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# K-Festia\n\nhttps://github.com/user-attachments/assets/181fca11-0cdb-4fac-92fc-c174c8f48762\n\n![example_graphql](https://github.com/user-attachments/assets/c48f0087-74fb-443e-82c6-d2d4edf144b0)\n![search](https://github.com/user-attachments/assets/f2554a6c-841b-4a0e-be02-12229e02f665)\n\n[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-brightgreen)](https://spring.io/projects/spring-boot)\n[![GraphQL](https://img.shields.io/badge/GraphQL-22.x-ff69b4)](https://graphql.org/)\n[![Java](https://img.shields.io/badge/Java-21%2B-blue)](https://www.oracle.com/java/)\n[![OpenAI](https://img.shields.io/badge/OpenAI-API-brightgreen)](https://openai.com/)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n## 🌟 Welcome to K-Festia!\n\nK-Festia is a Spring Boot 3 application designed to manage, translate, and categorize Korean festivals seamlessly.\n\nLeveraging the power of GraphQL, OpenAI's API,\n\nusers can effortlessly discover and explore festivals tailored to their interests.\n\n---\n\n## ✨ Features\n\n- **GraphQL API**: Flexible and efficient querying of festival data.\n- **Dual API Integration**: Fetch festival data from primary and secondary sources with robust fallback mechanisms.\n- **Automated Translation**: Translate festival names and summaries from Korean to English using OpenAI's API. (gpt-4o-mini)\n- **Intelligent Categorization**: Classify festivals into 10 predefined categories leveraging OpenAI's powerful language models.\n- **Pagination \u0026 Filtering**: Easily navigate through festival listings with advanced pagination and filtering options.\n- **Robust Error Handling**: Gracefully handle external API failures and data inconsistencies.\n- **Search**: Powered by Apache Lucene to search Korean/English texts among festivals. (name, summary, categories, address)\n\n---\n\n## 🛠️ Getting Started\n\n### Prerequisites\n\n- **Java 21+**: Virtual Thread support required\n- **Maven 4.0+**: For building the project.\n- **OpenAI API Key**: translation and categorization services.\n- **Redis (Optional)**: distributed caching.\n\n## 📡 GraphQL API\n\n### Sample Queries\n\n1. **Fetch Festivals with Pagination**\n\n   ```graphql\n   query {\n     getFestivals(month: \"09\", page: 0, size: 10) {\n       content {\n         id\n         name\n         summary\n         nameEn\n         summaryEn\n         address\n         naverUrl\n         categories\n         distance\n         latitude\n         longitude\n       }\n       pageNumber\n       pageSize\n       totalElements\n       totalPages\n     }\n   }\n   ```\n\n2. **Filter Festivals by Category**\n\n   ```graphql\n   query {\n     getFestivals(month: \"09\", page: 0, size: 5) {\n       content {\n         id\n         name\n         categories\n       }\n     }\n   }\n   ```\n\n3. **Retrieve Specific Festival Details**\n\n   ```graphql\n   query {\n     getFestivals(month: \"10\", page: 1, size: 5) {\n       content {\n         id\n         name\n         summary\n         categories\n       }\n     }\n   }\n   ```\n   \n4. **Simple Router planner by walking nearby stations**\n\n   ```graphql\n   query {\n     planFestivalRoute(\n     startStation: \"서울역\",\n      startDate: \"2024-10-01\",\n      endDate: \"2024-11-30\",\n      preferredCategories: [MUSIC_PERFORMING_ARTS, FOOD_CULINARY],\n      maxFestivals: 3) {\n          festivals {\n          name\n          startDate\n          endDate\n          address\n          categories\n          # default locale \"en\"\n          }\n        totalDistance\n        totalDuration\n      }\n   }\n   ```\n\n\u003e **Note**: Customize queries as per frontend requirements. Utilize GraphQL clients like [Apollo](https://www.apollographql.com/) for efficient data fetching.\n\n[![codecov](https://codecov.io/gh/Alfex4936/K-Festia/graph/badge.svg?token=5O9FFQ3QBN)](https://codecov.io/gh/Alfex4936/K-Festia)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfex4936%2Fk-festia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falfex4936%2Fk-festia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfex4936%2Fk-festia/lists"}