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.
Choose how to connect
Section titled “Choose how to connect”| 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.
Your first call
Section titled “Your first call”curl -fsS 'https://biz.ossalt.jp/v1/holidays?year=2026'The answer shape
Section titled “The answer shape”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. |
Conventions
Section titled “Conventions”- Dates are
YYYY-MM-DDin 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