/K-Festia

외국인을 위한 대한민국 전국 축제 (Korean festival information for foreigners)

Primary LanguageJava

K-Festia

example_graphql search

Spring Boot GraphQL Java OpenAI 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

    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

    query {
  getFestivals(month: "09", page: 0, size: 5) {
    content {
      id
      name
      categories
    }
  }
}

  3. Retrieve Specific Festival Details

    query {
  getFestivals(month: "10", page: 1, size: 5) {
    content {
      id
      name
      summary
      categories
    }
  }
}

  4. Simple Router planner by walking nearby stations

    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 for efficient data fetching.

codecov