문서

Nihonbase — Japan Data API 통합 방법 알아보기

빠른 시작

몇 분이면 Nihonbase — Japan Data API를 시작할 수 있습니다.

1
계정 만들기

무료 계정에 가입해 API 키를 받으세요. 신용카드는 필요 없습니다.

무료로 가입 →
2
API 키 받기

대시보드에서 API 키를 생성하세요. 비밀로 유지하고 안전하게 보관하세요.

3
첫 요청 보내기

API 키로 요청을 인증하고 데이터 조회를 시작하세요.

베이스 URL

https://api.nihonbase.com/api/v1

OpenAPI 명세

인증

모든 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월 ¥010010
Basic월 ¥1,7005,00060
Business월 ¥4,90050,000300

GET /health와 GET /plans는 할당량을 쓰지 않으며 API 키가 필요 없습니다.

API 엔드포인트

사용할 수 있는 모든 엔드포인트를 확인하세요.

지역
GET
/regions

모든 지역 목록(id, name, slug). 쿼리 파라미터 없음.

도도부현
GET
/prefectures

페이지네이션 목록. Params: page, limit(기본 50, 최대 200), region(slug, 예: kanto)

GET
/prefectures/{id}

도도부현을 지역과 함께 조회

GET
/prefectures/{id}/cities

도도부현의 시구정촌. Params: page, limit(최대 200)

시구정촌
GET
/cities

페이지네이션 목록. Params: page, limit(최대 200), prefecture(id 또는 로마자 이름)

GET
/cities/{id}

시구정촌을 도도부현·지역과 함께 조회

공휴일
GET
/holidays

페이지네이션 목록. Params: page, limit(최대 366), year

GET
/holidays/{year}

해당 연도의 모든 공휴일(1955–2027)

연호
GET
/era?date=YYYY-MM-DD

그레고리력 날짜를 일본 연호로 변환(1868–2100)

GET
/era?year=YYYY

그레고리력 연도를 일본 연호로 변환(1868–2100)

GET
/era/{year}

그레고리력 연도의 연호(1월 1일, Asia/Tokyo)

유틸리티
GET
/health

상태 확인(API 키 불필요)

GET
/plans

요금제 목록(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_REQUIRED401API 키가 없거나 유효하지 않습니다
RESOURCE_NOT_FOUND404리소스를 찾을 수 없습니다
VALIDATION_ERROR422요청 파라미터가 유효하지 않습니다
INVALID_ERA_INPUT422연호 변환용 날짜 또는 연도가 유효하지 않습니다
—429요청이 너무 많습니다(일일 할당량 또는 분당 한도)