PHPackages                             minhyung/korea-days - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. minhyung/korea-days

ActiveLibrary[API Development](/categories/api)

minhyung/korea-days
===================

PHP wrapper for Korea Days API

0.4.0(7mo ago)01.1k—4.2%MITPHPCI passing

Since Sep 20Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/overworks/php-korea-days)[ Packagist](https://packagist.org/packages/minhyung/korea-days)[ RSS](/packages/minhyung-korea-days/feed)WikiDiscussions 0.x Synced 2d ago

READMEChangelogDependencies (7)Versions (6)Used By (0)

PHP Korea Days
==============

[](#php-korea-days)

한국천문연구원에서 제공하는 특일 정보 API의 PHP 래퍼 라이브러리입니다.

소개
--

[](#소개)

이 라이브러리는 한국천문연구원의 특일 정보 API를 쉽게 사용할 수 있도록 PHP로 래핑한 것입니다. 국경일, 공휴일, 기념일, 24절기, 잡절 등 한국의 다양한 특별한 날짜 정보를 조회할 수 있습니다.

### 주요 기능

[](#주요-기능)

- 🎉 **국경일 정보 조회** - 3.1절, 광복절, 개천절 등
- 📅 **공휴일 정보 조회** - 설날, 추석, 어린이날 등
- 🎊 **기념일 정보 조회** - 식목일, 과학의 날, 스승의 날 등
- 🌸 **24절기 정보 조회** - 입춘, 춘분, 하지, 동지 등
- 📆 **잡절 정보 조회** - 한식, 초복, 중복, 말복 등

요구사항
----

[](#요구사항)

- PHP 8.0 이상
    - 현재 Composer 설정에는 PHP 버전 제약이 없지만, 이 라이브러리는 PHP 8.0 이상 환경에서만 동작합니다.
- PSR-18 HTTP 클라이언트 구현체 (예: Guzzle)
- PSR-17 HTTP Factory 구현체 (예: guzzlehttp/psr7, nyholm/psr7)
- 공공데이터포털에서 발급받은 API 서비스 키

설치
--

[](#설치)

Composer를 사용하여 설치할 수 있습니다:

```
composer require minhyung/korea-days
```

PSR-18 HTTP 클라이언트와 PSR-17 HTTP Factory가 없다면 Guzzle을 함께 설치하세요:

```
composer require minhyung/korea-days guzzlehttp/guzzle guzzlehttp/psr7
```

API 키 발급
--------

[](#api-키-발급)

1. [공공데이터포털](https://www.data.go.kr/data/15012690/openapi.do)에 접속
2. 회원가입 및 로그인
3. "한국천문연구원\_특일 정보" API 신청
4. 발급받은 서비스 키를 사용

사용법
---

[](#사용법)

### 기본 사용법

[](#기본-사용법)

```
use Minhyung\KoreaDays\Service;

// 서비스 객체 생성
$service = new Service('YOUR_SERVICE_KEY');

// 2024년 9월의 국경일 조회
$result = $service->getHoliDeInfo(2024, 9);

// 결과 출력
print_r($result);
```

### 응답 구조

[](#응답-구조)

모든 API 메서드는 동일한 구조의 배열을 반환합니다:

```
[
    'items' => [
        // 조회된 특일 정보 배열
        [
            'dateKind' => '01',           // 날짜 구분 코드
            'dateName' => '삼일절',       // 날짜 이름
            'isHoliday' => 'Y',           // 공휴일 여부
            'locdate' => '20240301',      // 날짜
            'seq' => '1',                 // 순번
        ],
        // ...
    ],
    'numOfRows' => 10,      // 한 페이지 결과 수
    'pageNo' => 1,          // 페이지 번호
    'totalCount' => 3,      // 전체 결과 수
]
```

### 사용 가능한 메서드

[](#사용-가능한-메서드)

#### 1. 국경일 정보 조회

[](#1-국경일-정보-조회)

```
$result = $service->getHoliDeInfo(
    year: 2024,        // 연도 (필수)
    month: 3,          // 월 (선택, 생략시 연간 전체)
    pageNo: 1,         // 페이지 번호 (기본값: 1)
    numOfRows: 10      // 페이지당 결과 수 (기본값: 10)
);
```

#### 2. 공휴일 정보 조회

[](#2-공휴일-정보-조회)

```
$result = $service->getRestDeInfo(
    year: 2024,
    month: 9,
    pageNo: 1,
    numOfRows: 10
);
```

#### 3. 기념일 정보 조회

[](#3-기념일-정보-조회)

```
$result = $service->getAnniversaryInfo(
    year: 2024,
    month: 5,
    pageNo: 1,
    numOfRows: 20      // 기념일은 많을 수 있으므로 필요시 증가
);
```

#### 4. 24절기 정보 조회

[](#4-24절기-정보-조회)

```
// 연간 24절기 전체 조회 (월 생략)
$result = $service->get24DivisionsInfo(
    year: 2024,
    month: null,       // null로 설정하면 연간 전체
    pageNo: 1,
    numOfRows: 24      // 24절기를 모두 가져오려면 24로 설정
);
```

#### 5. 잡절 정보 조회

[](#5-잡절-정보-조회)

```
$result = $service->getSundryDayInfo(
    year: 2024,
    month: 7,
    pageNo: 1,
    numOfRows: 10
);
```

### 사용자 정의 HTTP 클라이언트

[](#사용자-정의-http-클라이언트)

PSR-18 호환 HTTP 클라이언트를 직접 제공할 수 있습니다:

```
use GuzzleHttp\Client;
use Minhyung\KoreaDays\Service;

$httpClient = new Client([
    'timeout' => 10,
    'verify' => true,
]);

$service = new Service('YOUR_SERVICE_KEY', $httpClient);
```

예외 처리
-----

[](#예외-처리)

API 호출 중 오류가 발생하면 `ApiException`이 발생합니다:

```
use Minhyung\KoreaDays\Service;
use Minhyung\KoreaDays\ApiException;

try {
    $service = new Service('YOUR_SERVICE_KEY');
    $result = $service->getHoliDeInfo(2024, 3);
} catch (ApiException $e) {
    echo "API 오류: " . $e->getMessage();
    echo "오류 코드: " . $e->getCode();
    echo "HTTP 상태 코드: " . $e->getStatusCode();
}
```

테스트
---

[](#테스트)

테스트를 실행하려면 환경 변수에 서비스 키를 설정해야 합니다:

```
# .env 파일 또는 환경 변수로 설정
export SERVICE_KEY=your_service_key_here

# 테스트 실행
composer test
```

라이선스
----

[](#라이선스)

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

관련 링크
-----

[](#관련-링크)

- [공공데이터포털 - 한국천문연구원 특일 정보](https://www.data.go.kr/data/15012690/openapi.do)
- [한국천문연구원 정보공개&활용](https://astro.kasi.re.kr/information/pageView/31)
- [GitHub 저장소](https://github.com/overworks/php-korea-days)
- [이슈 트래커](https://github.com/overworks/php-korea-days/issues)

기여
--

[](#기여)

버그 리포트, 기능 제안, 풀 리퀘스트는 언제나 환영합니다!

작성자
---

[](#작성자)

- **Minhyung Park** -

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance69

Regular maintenance activity

Popularity18

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 Bus Factor1

Top contributor holds 85% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~124 days

Total

5

Last Release

155d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/381cd0165a6aa9f238950dc1ae39f15a2b01a3dc33c111cd0fc1b12ab4259100?d=identicon)[lostland](/maintainers/lostland)

---

Top Contributors

[![overworks](https://avatars.githubusercontent.com/u/2780002?v=4)](https://github.com/overworks "overworks (17 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (3 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/minhyung-korea-days/health.svg)

```
[![Health](https://phpackages.com/badges/minhyung-korea-days/health.svg)](https://phpackages.com/packages/minhyung-korea-days)
```

###  Alternatives

[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35789.4k2](/packages/telnyx-telnyx-php)[openai-php/client

OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API

5.8k28.0M318](/packages/openai-php-client)[n1ebieski/ksef-php-client

PHP API client that allows you to interact with the API Krajowego Systemu e-Faktur

9067.8k](/packages/n1ebieski-ksef-php-client)[trycourier/courier

Courier PHP SDK

15660.9k](/packages/trycourier-courier)[deeplcom/deepl-php

Official DeepL API Client Library

2607.3M114](/packages/deeplcom-deepl-php)[anthropic-ai/sdk

Anthropic PHP SDK

163583.3k17](/packages/anthropic-ai-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)