Quick Start
Get started with Nihonbase — Japan Data API in minutes.
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_KEYAlternatively, 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.
| Plan | Price | Requests / day | Requests / min |
|---|---|---|---|
| Free | ¥0 / month | 100 | 10 |
| Basic | ¥1,700 / month | 5,000 | 60 |
| Business | ¥4,900 / month | 50,000 | 300 |
GET /health and GET /plans do not consume quota and do not require an API key.
API Endpoints
Explore all available endpoints.
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
| Code | HTTP Status | Description |
|---|---|---|
| API_KEY_REQUIRED | 401 | Missing or invalid API key |
| RESOURCE_NOT_FOUND | 404 | Resource not found |
| VALIDATION_ERROR | 422 | Invalid request parameters |
| INVALID_ERA_INPUT | 422 | Invalid date or year for era conversion |
| — | 429 | Too many requests (daily quota or per-minute rate limit) |