# japan-agent-api

> Japan data for AI agents in English: JMA weather warnings, typhoon bulletins, volcanic alert levels, municipality code history with convenience-store certificate availability, and paid checks (x402, USDC). Relay of official sources only; no forecasts.

Data sources: Japan Meteorological Agency (JMA) disaster-prevention XML (warnings, typhoons, volcanoes); e-Stat Statistical LOD (municipality codes and change history, CC BY 4.0); J-LIS list of municipalities offering convenience-store certificate issuance. Relayed and restructured into English by MK Career Planning.
This service relays official bulletins and records only. It makes no forecast, does not issue warnings of its own, and gives no legal advice. Always confirm with the official source.
Every response carries provenance (source, upstream_updated_at or null, retrieved_at, content_sha256, parser_version, fetch_status found/empty/stale/unavailable/unsupported).

## Connect

- Paid HTTP (x402 v2): POST https://japan-agent-api-production.mk-career-planning.workers.dev/v1/trip-impact-check (jp_trip_impact_check)
- Paid HTTP (x402 v2): POST https://japan-agent-api-production.mk-career-planning.workers.dev/v1/municipalities/batch (jp_municipality_batch)
- MCP (streamable HTTP): https://japan-agent-api-production.mk-career-planning.workers.dev/mcp
- OpenAPI: https://japan-agent-api-production.mk-career-planning.workers.dev/openapi.json
- x402 discovery: https://japan-agent-api-production.mk-career-planning.workers.dev/.well-known/x402

## Free tools

- catalog: List the tools of this server with prices, data sources, licensing, daily limits and data freshness.
- jp_warnings: Current Japan Meteorological Agency (JMA) weather emergency warnings, warnings and advisories for one prefecture, as structured JSON in English and Japanese (type, level, status, areas with JMA's English names, issued_at, source URL). Relay only; no independent forecast.
- jp_typhoons: Typhoons JMA is currently issuing bulletins for: number, name, center position, central pressure, maximum wind, issue time, and forecast-circle centers, radii and times, relayed as structured JSON from JMA bulletins (VPTW60-65). No independent forecast, interpolation or track extension.
- jp_volcanoes: Current JMA Volcanic Alert Levels (1-5) or warning kinds for volcanoes without levels, for all JMA-monitored volcanoes or one (name in English or Japanese, or 3-digit JMA code): JMA English and Japanese names, level, previous level and change, issue time, prefectures named in JMA bulletins, source URL and freshness receipt. Relay only; no forecast or interpretation. Volcanoes with no bulletin seen yet are not_seen_in_checked_feeds, never assumed level 1.
- jp_municipality: Look up one Japanese municipality code as of a date (default today): give a 5/6-digit code, or prefecture and name (old names OK). Returns status mapped / split_candidates / unknown / invalid, the valid code with English and Japanese names, change type and date (merger, incorporation, division, designated city, name change), confirmed JMA warning areas only, and J-LIS convenience-store certificate availability for 8 certificate types. Facts only, from e-Stat LOD (CC BY 4.0) and J-LIS.
- get_receipt: Re-fetch the stored result of a settled paid call (e.g. jp_trip_impact_check) by its receipt_id, for when the response was lost after payment. Free. Unknown or unsettled receipt ids return RECEIPT_NOT_FOUND. Results are kept for 90 days after settlement.
- HTTP: GET https://japan-agent-api-production.mk-career-planning.workers.dev/v1/warnings?prefecture=Tokyo, GET https://japan-agent-api-production.mk-career-planning.workers.dev/v1/typhoons, GET https://japan-agent-api-production.mk-career-planning.workers.dev/v1/volcanoes?volcano=Sakurajima, GET https://japan-agent-api-production.mk-career-planning.workers.dev/v1/municipalities/22131?as_of=2026-10-10 and GET https://japan-agent-api-production.mk-career-planning.workers.dev/v1/municipalities?prefecture=Shizuoka&name=Naka-ku return the same data as the MCP tools. GET https://japan-agent-api-production.mk-career-planning.workers.dev/v1/receipts/<receipt_id> is get_receipt.

## Paid tools (x402, USDC)

- jp_trip_impact_check ($0.03 per call, eip155:8453): Check a Japan itinerary [{date, prefecture}] against JMA warnings/advisories in effect now. Per stop: matched_advisory (with severity), no_match_in_checked_sources (NOT a statement of no impact) or unknown (data missing, or date not today/tomorrow JST). Returns checked sources and areas, unchecked areas, issued_at, retrieved_at, and current JMA typhoon bulletins (listed, not matched). No forecast. Retrying with the same payment is not charged; use receipt_id with get_receipt.
- jp_municipality_batch ($0.03 per call, eip155:8453): Batch (up to 50) Japanese municipality code lookups as of a date, from e-Stat LOD change history (CC BY 4.0): status mapped / split_candidates (all successors, not apportioned) / unknown / invalid, the code valid on as_of with English and Japanese names, change type and date, confirmed JMA warning areas only, and J-LIS convenience-store certificate availability (available / not_listed / unknown). Facts only; no document preparation or legal advice. Retrying with the same payment is not charged.

### Pay over HTTP (x402 v2)

1. POST the JSON body without payment. The answer is HTTP 402 with a PAYMENT-REQUIRED header: base64 JSON of the x402 v2 PaymentRequired (scheme exact, USDC, amount 30000 = $0.03). The body repeats it. The municipality batch body is {"items":[{"code":"22131"}],"as_of":"2026-10-10"} with 1 to 50 items.
2. Sign the payment with an x402 v2 client and POST the same body again with the PAYMENT-SIGNATURE header (base64 PaymentPayload).
3. On success: HTTP 200, the result JSON with receipt_id, and a PAYMENT-RESPONSE header (base64 SettlementResponse with the transaction hash). If verification or settlement fails you get 402 again, no result, and no charge.
4. Retrying with the same PAYMENT-SIGNATURE returns the stored result and the same receipt_id without charging again.

```sh
curl -i -X POST https://japan-agent-api-production.mk-career-planning.workers.dev/v1/trip-impact-check -H 'Content-Type: application/json' -d '{"itinerary":[{"date":"2026-10-10","prefecture":"Tokyo"}]}'
```

```ts
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
const client = new x402Client();
registerExactEvmScheme(client, { signer }); // signer: an EVM account holding USDC
const pay = wrapFetchWithPayment(fetch, client);
const res = await pay("https://japan-agent-api-production.mk-career-planning.workers.dev/v1/trip-impact-check", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ itinerary: [{ date: "2026-10-10", prefecture: "Tokyo" }] }) });
```

### Pay over MCP

Call the tool without payment to receive the x402 requirement in the result _meta 'x402/error', then retry with the signed payment in _meta 'x402/payment'.

Both ways share one ledger, one receipt store and one daily limit.
Daily limits apply (Japan time); when reached the tool returns DAILY_CAP_REACHED (HTTP 429) and does not charge.

## Provenance and fetch_status

Responses carry provenance[] (source, upstream_updated_at, retrieved_at, content_sha256, parser_version, fetch_status). fetch_status values:

- found: The upstream document was retrieved and contains the data used for this answer.
- empty: The upstream was retrieved, but it has no item for this query (for example JMA had no bulletin for that area in its feeds, or the municipality is not in the list). The state is unknown: empty does NOT mean 'none in effect'.
- stale: The data was retrieved but is older than the freshness threshold for its kind; treat it with care.
- unavailable: The upstream could not be retrieved, read or used (network error, withdrawn bulletin, paused source, or data not yet loaded).
- unsupported: The query is outside what this source covers (for example a date JMA does not issue warnings for yet, or a period before the source's records).

## Errors

- PAYMENT_REQUIRED (x402; pay and retry)
- INVALID_PAYMENT / insufficient_funds (not charged)
- PAYMENT_ALREADY_USED (payment settled for different arguments; not charged again)
- PAYMENT_IN_PROGRESS (retry shortly with the same payment)
- DAILY_CAP_REACHED (daily limit in Japan time; not charged; see resets_at)
- PAUSED (operator pause; not charged)
- LEDGER_UNAVAILABLE (refused; not charged)
- UPSTREAM_ERROR (JMA unreachable; not charged)
- PAYMENT_REQUIRED (x402; pay and retry)
- INVALID_INPUT (more than 50 items or malformed body; not charged)
- INVALID_PAYMENT / insufficient_funds (not charged)
- PAYMENT_ALREADY_USED (payment settled for different arguments; not charged again)
- PAYMENT_IN_PROGRESS (retry shortly with the same payment)
- DAILY_CAP_REACHED (daily limit shared with all paid tools, Japan time; not charged)
- PAUSED (operator pause of e-Stat or J-LIS data; not charged)
- MUNICIPALITY_DATA_UNAVAILABLE (data not loaded yet; not charged)
- LEDGER_UNAVAILABLE (refused; not charged)
- UNKNOWN_PREFECTURE (free tools; use an English name, Japanese name or JIS code)
- UNKNOWN_VOLCANO (jp_volcanoes; ambiguous names return candidates)
- MUNICIPALITY_DATA_UNAVAILABLE (municipality data not loaded yet; not charged)
- RECEIPT_NOT_FOUND (get_receipt)

## Terms

- Results for no_match_in_checked_sources mean only that no JMA warning matched within the checked sources at retrieved_at; they do not mean there is no impact.
- Typhoon bulletins are listed as issued by JMA and are not matched against places.
- Relay of JMA bulletins only: not a forecast, and no guarantee of safety.
- Volcanoes: JMA levels as issued; a volcano with no bulletin seen is not_seen_in_checked_feeds, never assumed level 1.
- Municipalities: split_candidates lists all successors without apportioning; not_listed means not in the J-LIS list on its date, not that certificates cannot be obtained. Facts only; no document preparation or legal advice.

## Privacy and support

- Operator: MK Career Planning
- Terms of Service: https://japan-agent-api-production.mk-career-planning.workers.dev/terms
- Privacy policy: https://japan-agent-api-production.mk-career-planning.workers.dev/privacy
- Support (free): https://japan-agent-api-production.mk-career-planning.workers.dev/support (mk.career.planning@gmail.com)