빠른 시작
몇 분이면 Nihonbase — Japan Data API를 시작할 수 있습니다.
인증
모든 API 요청은 API 키 인증이 필요합니다. X-API-Key 헤더에 키를 넣으세요:
API 키가 공개되지 않도록 브라우저의 JavaScript가 아니라 서버에서 API를 호출하세요.
X-API-Key: YOUR_API_KEY또는 Authorization: Bearer YOUR_API_KEY를 사용할 수 있습니다(YOUR_API_KEY는 jda_… 키이며 세션 토큰이 아닙니다).
속도 제한과 요금
한도는 API 키가 아니라 계정 단위입니다. 일일 할당량이나 분당 한도를 초과하면 HTTP 429가 반환됩니다.
| 플랜 | 요금 | 요청/일 | 요청/분 |
|---|---|---|---|
| Free | 월 ¥0 | 100 | 10 |
| Basic | 월 ¥1,700 | 5,000 | 60 |
| Business | 월 ¥4,900 | 50,000 | 300 |
GET /health와 GET /plans는 할당량을 쓰지 않으며 API 키가 필요 없습니다.
API 엔드포인트
사용할 수 있는 모든 엔드포인트를 확인하세요.
코드 예제
자주 쓰는 프로그래밍 언어의 예제입니다.
curl -X GET "https://api.nihonbase.com/api/v1/prefectures" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Accept: application/json"응답 형식
모든 응답은 다음의 일관된 JSON 구조를 따릅니다:
{
"success": true,
"data": [
{
"id": 1,
"name": "Hokkaido",
"name_ja": "北海道",
"name_en": "Hokkaido",
"slug": "hokkaido",
"iso_code": "JP-01",
"region_id": 1,
"capital": "Sapporo",
"area_km2": 83424,
"population": 5224614
},
{
"id": 2,
"name": "Aomori",
"name_ja": "青森県",
"name_en": "Aomori",
"slug": "aomori",
"iso_code": "JP-02",
"region_id": 2,
"capital": "Aomori",
"area_km2": 9645,
"population": 1237984
}
],
"meta": {
"page": 1,
"limit": 50,
"total": 47
},
"error": null
}연호 변환
GET /era?date=2026-03-01은 그레고리력 날짜(또는 ?year=YYYY)를 일본 연호로 변환합니다. 연호의 1년차는 label_ja에서 元年입니다.
{
"success": true,
"data": {
"gregorian_year": 2026,
"reference_date": "2026-03-01",
"era": {
"slug": "reiwa",
"name_en": "Reiwa",
"name_ja": "令和",
"year": 8,
"gannen": false,
"label_en": "Reiwa 8",
"label_ja": "令和8年"
}
},
"meta": [],
"error": null
}오류 처리
오류가 나면 API는 다음 구조의 오류 응답을 반환합니다:
{
"success": false,
"data": null,
"meta": {},
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found."
}
}자주 나오는 오류 코드
| 코드 | HTTP 상태 | 설명 |
|---|---|---|
| API_KEY_REQUIRED | 401 | API 키가 없거나 유효하지 않습니다 |
| RESOURCE_NOT_FOUND | 404 | 리소스를 찾을 수 없습니다 |
| VALIDATION_ERROR | 422 | 요청 파라미터가 유효하지 않습니다 |
| INVALID_ERA_INPUT | 422 | 연호 변환용 날짜 또는 연도가 유효하지 않습니다 |
| — | 429 | 요청이 너무 많습니다(일일 할당량 또는 분당 한도) |