Documentação

Aprenda a integrar Nihonbase — Japan Data API

Início rápido

Comece a usar Nihonbase — Japan Data API em minutos.

1
Crie uma conta

Cadastre-se gratuitamente para obter sua chave de API. Sem cartão de crédito.

Cadastre-se grátis →
2
Obtenha sua chave de API

Gere uma chave de API no painel. Mantenha-a secreta e segura.

3
Faça sua primeira requisição

Use a chave de API para autenticar as requisições e começar a buscar dados.

URL base

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

Especificação OpenAPI

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_KEY

Como 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.

PlanoPreçoRequisições / diaRequisições / min
Grátis¥0 / mês10010
Basic¥1.700 / mês5.00060
Business¥4.900 / mês50.000300

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.

Regiões
GET
/regions

Lista todas as regiões (id, name, slug). Sem parâmetros de consulta.

Prefeituras
GET
/prefectures

Lista paginada. Params: page, limit (padrão 50, máx. 200), region (slug, ex.: kanto)

GET
/prefectures/{id}

Obtém uma prefeitura com a respectiva região

GET
/prefectures/{id}/cities

Cidades de uma prefeitura. Params: page, limit (máx. 200)

Cidades
GET
/cities

Lista paginada. Params: page, limit (máx. 200), prefecture (id ou nome em romaji)

GET
/cities/{id}

Obtém uma cidade com a prefeitura e a região

Feriados
GET
/holidays

Lista paginada. Params: page, limit (máx. 366), year

GET
/holidays/{year}

Todos os feriados de um ano (1955–2027)

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

Converte uma data gregoriana para a era japonesa (1868–2100)

GET
/era?year=YYYY

Converte um ano gregoriano para a era japonesa (1868–2100)

GET
/era/{year}

Era de um ano gregoriano (1º de janeiro, Asia/Tokyo)

Utilitários
GET
/health

Verificação de saúde (não exige chave de API)

GET
/plans

Lista os planos de preços (não exige chave de API)

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ódigoStatus HTTPDescrição
API_KEY_REQUIRED401Chave de API ausente ou inválida
RESOURCE_NOT_FOUND404Recurso não encontrado
VALIDATION_ERROR422Parâmetros de requisição inválidos
INVALID_ERA_INPUT422Data ou ano inválido para conversão de era
—429Muitas requisições (cota diária ou limite por minuto)