Japanese Address Normalization API for AI Agents

Japanese addresses are written in many formats — full-width digits, kanji prefecture omitted, postal-code prefix, etc. Torify parses raw addresses into structured components including v0.3.0 fields: addressType (block/street/rural/other), streetRef for Kyoto street intersections, and addressee for 様方/気付/c-o extraction.

Endpoint

GET https://torify.dev/v1/address/normalize

Parameters

Name	Type	Required	Description	Example
`address`	string	Yes	Raw Japanese address string (max 200 chars)	`東京都千代田区霞が関3丁目1番1号`

Response example

{
  "ok": true,
  "data": {
    "original": "東京都千代田区霞が関3丁目1番1号",
    "prefecture": "東京都",
    "prefectureEn": "Tokyo",
    "city": "千代田区",
    "cityEn": "Chiyoda-ku",
    "town": "霞が関3丁目1番1号",
    "townEn": null,
    "normalized": "東京都千代田区霞が関3丁目1番1号",
    "source": "geolonia",
    "streetNumber": "3丁目1番1号",
    "streetNumberHyphen": "3-1-1",
    "streetNumberFormal": "3丁目1番1号",
    "level": 3,
    "point": null,
    "engine": "geolonia",
    "addressType": "block",
    "streetRef": null,
    "addressee": null
  }
}

Code examples

curl

curl "https://torify.dev/v1/address/normalize?address=%E6%9D%B1%E4%BA%AC%E9%83%BD%E5%8D%83%E4%BB%A3%E7%94%B0%E5%8C%BA%E9%9C%9E%E3%81%8C%E9%96%A23%E4%B8%81%E7%9B%AE1%E7%95%AA1%E5%8F%B7"

TypeScript (x402-fetch)

import { wrapFetchWithPayment } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

const res = await fetchWithPayment(
  'https://torify.dev/v1/address/normalize?address=%E6%9D%B1%E4%BA%AC%E9%83%BD%E5%8D%83%E4%BB%A3%E7%94%B0%E5%8C%BA%E9%9C%9E%E3%81%8C%E9%96%A23%E4%B8%81%E7%9B%AE1%E7%95%AA1%E5%8F%B7'
);
const data = await res.json();
console.log(data); // { ok: true, data: { ... } }

Python (requests)

import requests

# Free MCP tier (no auth) or API key (X-API-Key header)
res = requests.get(
    "https://torify.dev/v1/address/normalize?address=%E6%9D%B1%E4%BA%AC%E9%83%BD%E5%8D%83%E4%BB%A3%E7%94%B0%E5%8C%BA%E9%9C%9E%E3%81%8C%E9%96%A23%E4%B8%81%E7%9B%AE1%E7%95%AA1%E5%8F%B7",
    headers={"X-API-Key": "your_torify_pro_key"}
)
print(res.json())

Use cases

AI agent normalizing scraped Japanese addresses

Agents extracting addresses from web pages can parse them into prefecture/city/town/block components for downstream geocoding or deduplication.

Kyoto street address parsing (通り名)

For Kyoto addresses with street intersection directions (上る/下る/東入/西入), streetRef returns the intersection name and canonical direction.

Delivery address extraction with addressee

When an address includes 様方 or 気付, the addressee field extracts the recipient name, leaving the normalized delivery address clean.

Edge cases & gotchas

addressType=block is assigned when streetNumber is non-null or when 丁目/番地/号/hyphen-digits are present.
addressType=street requires a Kyoto-style street name (通/筋/小路) followed by 上る/下る/東入る/西入る.
addressType=rural requires 大字/字 prefix; common kanji like 大文字町 are excluded via lookbehind.
streetRef direction values are canonicalized: 東入る → 東入, 西入る → 西入.

Related endpoints

/v1/postal/lookup — Japan Postal Code Lookup: Zipcode → Address API
/v1/region/lookup — Japan Region Code Lookup: JIS X 0402 API
/v1/coordinate/convert — Japan Coordinate Conversion API: WGS84 ↔ JGD2011

← All 42 endpoints

Pricing

$0.02 per call via x402 (USDC on Base). Or use a Pro API key ($19/mo, 10,000 calls/month).

View pricing Code examples ↗