Documentation

Learn how to integrate Nihonbase — Japan Data API

Quick Start

Get started with Nihonbase — Japan Data API in minutes.

1
Create an Account

Sign up for a free account to get your API key. No credit card required.

Sign up free →
2
Get Your API Key

Generate an API key from your dashboard. Keep it secret and secure.

3
Make Your First Request

Use your API key to authenticate requests and start fetching data.

Base URL

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

OpenAPI specification

Authentication

All API requests require authentication via an API key. Include your key in the X-API-Key header:

Call the API from your server, not from browser JavaScript, so your API key stays private.

X-API-Key: YOUR_API_KEY

Alternatively, you can use Authorization: Bearer YOUR_API_KEY (where YOUR_API_KEY is your jda_… key, not a session token).

Rate limits and pricing

Limits are per account, not per API key. Exceeding the daily quota or the per-minute limit returns HTTP 429.

PlanPriceRequests / dayRequests / min
Free¥0 / month10010
Basic¥1,700 / month5,00060
Business¥4,900 / month50,000300

GET /health and GET /plans do not consume quota and do not require an API key.

API Endpoints

Explore all available endpoints.

Regions
GET
/regions

List all regions (id, name, slug). No query params.

Prefectures
GET
/prefectures

Paginated list. Params: page, limit (default 50, max 200), region (slug, e.g. kanto)

GET
/prefectures/{id}

Get a prefecture with its region

GET
/prefectures/{id}/cities

Cities in a prefecture. Params: page, limit (max 200)

Cities
GET
/cities

Paginated list. Params: page, limit (max 200), prefecture (id or romaji name)

GET
/cities/{id}

Get a city with its prefecture and region

Holidays
GET
/holidays

Paginated list. Params: page, limit (max 366), year

GET
/holidays/{year}

All holidays in a year (1955–2027)

Era
GET
/era?date=YYYY-MM-DD

Convert a Gregorian date to Japanese era (1868–2100)

GET
/era?year=YYYY

Convert a Gregorian year to Japanese era (1868–2100)

GET
/era/{year}

Era for a Gregorian year (Jan 1, Asia/Tokyo)

Utility
GET
/health

Health check (no API key required)

GET
/plans

List pricing plans (no API key required)

Code Examples

Examples in popular programming languages.

curl -X GET "https://api.nihonbase.com/api/v1/prefectures" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Response Format

All responses follow a consistent JSON structure:

{
  "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
}

Era conversion

GET /era?date=2026-03-01 converts a Gregorian date (or ?year=YYYY) to its Japanese era. Year 1 of an era is 元年 in 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
}

Error Handling

When an error occurs, the API returns a structured error response:

{
  "success": false,
  "data": null,
  "meta": {},
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Common Error Codes

CodeHTTP StatusDescription
API_KEY_REQUIRED401Missing or invalid API key
RESOURCE_NOT_FOUND404Resource not found
VALIDATION_ERROR422Invalid request parameters
INVALID_ERA_INPUT422Invalid date or year for era conversion
—429Too many requests (daily quota or per-minute rate limit)