https://github.com/alfex4936/k-festia
외국인을 위한 대한민국 전국 축제 (Korean festival information for foreigners)
https://github.com/alfex4936/k-festia
festival graphql korea lucene south-korea spring spring-boot
Last synced: about 2 months ago
JSON representation
외국인을 위한 대한민국 전국 축제 (Korean festival information for foreigners)
- Host: GitHub
- URL: https://github.com/alfex4936/k-festia
- Owner: Alfex4936
- Created: 2024-09-28T12:18:10.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-01-09T04:54:21.000Z (5 months ago)
- Last Synced: 2025-04-07T00:52:25.150Z (about 2 months ago)
- Topics: festival, graphql, korea, lucene, south-korea, spring, spring-boot
- Language: Java
- Homepage:
- Size: 1.57 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# K-Festia
[](https://spring.io/projects/spring-boot)
[](https://graphql.org/)
[](https://www.oracle.com/java/)
[](https://openai.com/)
[](LICENSE)
## 🌟 Welcome to K-Festia!
K-Festia is a Spring Boot 3 application designed to manage, translate, and categorize Korean festivals seamlessly.
Leveraging the power of GraphQL, OpenAI's API,
users can effortlessly discover and explore festivals tailored to their interests.
---
## ✨ Features
- **GraphQL API**: Flexible and efficient querying of festival data.
- **Dual API Integration**: Fetch festival data from primary and secondary sources with robust fallback mechanisms.
- **Automated Translation**: Translate festival names and summaries from Korean to English using OpenAI's API. (gpt-4o-mini)
- **Intelligent Categorization**: Classify festivals into 10 predefined categories leveraging OpenAI's powerful language models.
- **Pagination & Filtering**: Easily navigate through festival listings with advanced pagination and filtering options.
- **Robust Error Handling**: Gracefully handle external API failures and data inconsistencies.
- **Search**: Powered by Apache Lucene to search Korean/English texts among festivals. (name, summary, categories, address)
---
## 🛠️ Getting Started
### Prerequisites
- **Java 21+**: Virtual Thread support required
- **Maven 4.0+**: For building the project.
- **OpenAI API Key**: translation and categorization services.
- **Redis (Optional)**: distributed caching.
## 📡 GraphQL API
### Sample Queries
1. **Fetch Festivals with Pagination**
```graphql
query {
getFestivals(month: "09", page: 0, size: 10) {
content {
id
name
summary
nameEn
summaryEn
address
naverUrl
categories
distance
latitude
longitude
}
pageNumber
pageSize
totalElements
totalPages
}
}
```
2. **Filter Festivals by Category**
```graphql
query {
getFestivals(month: "09", page: 0, size: 5) {
content {
id
name
categories
}
}
}
```
3. **Retrieve Specific Festival Details**
```graphql
query {
getFestivals(month: "10", page: 1, size: 5) {
content {
id
name
summary
categories
}
}
}
```
4. **Simple Router planner by walking nearby stations**
```graphql
query {
planFestivalRoute(
startStation: "서울역",
startDate: "2024-10-01",
endDate: "2024-11-30",
preferredCategories: [MUSIC_PERFORMING_ARTS, FOOD_CULINARY],
maxFestivals: 3) {
festivals {
name
startDate
endDate
address
categories
# default locale "en"
}
totalDistance
totalDuration
}
}
```
> **Note**: Customize queries as per frontend requirements. Utilize GraphQL clients like [Apollo](https://www.apollographql.com/) for efficient data fetching.
[](https://codecov.io/gh/Alfex4936/K-Festia)