Início rápido
Comece a usar Nihonbase — Japan Data API em minutos.
Autenticação
Todas as requisições à API exigem autenticação por chave de API. Inclua a chave no cabeçalho X-API-Key:
Chame a API a partir do seu servidor, não do JavaScript do navegador, para que a sua chave de API permaneça privada.
X-API-Key: YOUR_API_KEYComo alternativa, você pode usar Authorization: Bearer YOUR_API_KEY (onde YOUR_API_KEY é a sua chave jda_…, não um token de sessão).
Limites e preços
Os limites são por conta, não por chave de API. Exceder a cota diária ou o limite por minuto retorna HTTP 429.
| Plano | Preço | Requisições / dia | Requisições / min |
|---|---|---|---|
| Grátis | ¥0 / mês | 100 | 10 |
| Basic | ¥1.700 / mês | 5.000 | 60 |
| Business | ¥4.900 / mês | 50.000 | 300 |
GET /health e GET /plans não consomem cota e não exigem chave de API.
Endpoints da API
Explore todos os endpoints disponíveis.
Exemplos de código
Exemplos em linguagens de programação populares.
curl -X GET "https://api.nihonbase.com/api/v1/prefectures" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Accept: application/json"Formato da resposta
Todas as respostas seguem uma estrutura JSON consistente:
{
"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
}Conversão de era
GET /era?date=2026-03-01 converte uma data gregoriana (ou ?year=YYYY) para a era japonesa. O ano 1 de uma era é 元年 em 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
}Tratamento de erros
Quando ocorre um erro, a API devolve uma resposta de erro estruturada:
{
"success": false,
"data": null,
"meta": {},
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found."
}
}Códigos de erro comuns
| Código | Status HTTP | Descrição |
|---|---|---|
| API_KEY_REQUIRED | 401 | Chave de API ausente ou inválida |
| RESOURCE_NOT_FOUND | 404 | Recurso não encontrado |
| VALIDATION_ERROR | 422 | Parâmetros de requisição inválidos |
| INVALID_ERA_INPUT | 422 | Data ou ano inválido para conversão de era |
| — | 429 | Muitas requisições (cota diária ou limite por minuto) |