Skip to content

Getting started

Japan Business Tools gives AI agents and developers 13 MCP tools and 13 REST endpoints for Japanese business data: holidays and business days, Japanese eras (wareki), postal codes, address normalization and corporate numbers. Both interfaces run the same logic and return the same answer shape.

I want to… Go to
connect an AI agent MCP guide
call HTTPS endpoints from code REST guide
see every tool and its inputs Tool reference
browse the OpenAPI definition API reference
try it in the browser Playground

No account, API key or sign-in is needed. All 13 tools are read-only.

Terminal window
curl -fsS 'https://biz.ossalt.jp/v1/holidays?year=2026'

Every successful answer has the same five fields, over MCP and over REST:

{
"result": {},
"source": {},
"as_of": "YYYY-MM-DD",
"notes": [],
"flags": []
}
Field Meaning
result The answer itself. Its fields depend on the tool (see the tool reference).
source Where the answer comes from: the data set, its version or update date, the licence, and how it was verified.
as_of The reference date, in Japan time (YYYY-MM-DD).
notes Human-readable notes (Japanese text): assumptions, estimates, hints.
flags Machine-readable codes for the things a caller should not miss. Always an array.

Check flags before you treat an answer as fact. When a flag marked “tell the user” is present, pass it on.

Flag Meaning
estimated A value is an estimate, for example a future equinox day. Tell the user.
unverified The year has not been checked against Cabinet Office data yet. Tell the user.
assumes_current_era A future date written in Japanese-era form assumes the era does not change. Tell the user. (to_japanese_era only.)
outside_era The era date given falls outside that era. The correct era date is returned in actual.
weekday_mismatch The weekday written in the input does not match the date.
closed The corporation’s registry record is closed. Tell the user.
excluded_from_search The record is marked “excluded from search” in the National Tax Agency data. Name search never returns it; lookup by number does.
truncated More results exist than were returned. Compare total and returned.
not_found Nothing matched. This is a valid answer, not an error.
exact_match_only The name was too common for a prefix search, so only names exactly equal to it were searched. Enter more characters.
partial The address was matched only down to a prefecture or city, not to a town (level below 3).
ambiguous More than one city or postal code candidate fits.
city_not_found search_postal_code: the city did not match any municipality.
ambiguous_city search_postal_code: the city name matches more than one municipality.
  • Dates are YYYY-MM-DD in Japan time. Holidays are available for 1980–2099; dates before 1873-01-01 cannot be converted to Japanese eras.
  • Input text is limited to 200 characters per field.
  • Limits and error handling are described in the MCP guide and the REST guide. Sources, freshness and known limits are on Trust & transparency.

Operated by Momonga