# 法人くん (Houjin-kun)

> Free REST API for searching Japanese corporate numbers, invoice registration numbers, and EDINET listed company codes. No registration required, no rate limits, no cost.

The service has been running since January 2015 and provides programmatic access to ~2.4M corporations, ~3M invoice registration numbers (適格請求書発行事業者), and ~4K EDINET-listed companies sourced from Japan's National Tax Agency (国税庁).

## Quick Start for AI Agents

The 3 most useful operations:

1. **Look up a company by name**: `GET https://corporation.teraren.com/corporations.json?s=トヨタ自動車`
2. **Get corporation details by number**: `GET https://corporation.teraren.com/corporations/1070001005817.json`
3. **Verify an invoice registration number**: `GET https://corporation.teraren.com/invoice_registration_numbers/T4010301136081.json`

All endpoints are unauthenticated, return JSON, and are CDN-cached for fast response (~70ms).

## MCP Server

An MCP (Model Context Protocol) server is available for direct AI tool integration:

```bash
npx -y mcp-server-corporation
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "corporation": {
      "command": "npx",
      "args": ["-y", "mcp-server-corporation"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add corporation -- npx -y mcp-server-corporation
```

The MCP server provides 5 tools: `search_corporations`, `get_corporation`, `search_invoice_numbers`, `get_invoice_number`, `search_edinets`.

## Common Use Cases

### Look up a company by name

```bash
curl "https://corporation.teraren.com/corporations.json?s=日本郵便"
```

Returns a paginated list of matching corporations with corporate numbers, addresses, and linked invoice registration numbers.

### Get corporation details by corporate number

```bash
curl "https://corporation.teraren.com/corporations/1070001005817.json"
```

Returns full details for Japan Post (日本郵便株式会社) including address, entity type, and invoice registration status.

### Verify an invoice registration number

```bash
curl "https://corporation.teraren.com/invoice_registration_numbers/T4010301136081.json"
```

Returns the registration details including business name, address, registration date, and linked corporation data.

### Find listed companies (EDINET)

```bash
curl "https://corporation.teraren.com/edinets.json?s=トヨタ"
```

Returns EDINET records with securities codes, listing status, and capital information.

### Find companies in a specific city

```bash
# Step 1: Get prefecture ID (Tokyo = 13)
curl "https://corporation.teraren.com/prefectures.json"

# Step 2: List cities in a prefecture
curl "https://corporation.teraren.com/prefectures/13.json"

# Step 3: List corporations in a specific city (URL-encoded city name)
curl "https://corporation.teraren.com/prefectures/13/areas/港区"
```

### Get a single field as plain text

```bash
# Get just the company name
curl "https://corporation.teraren.com/corporations/1070001005817/text/name"
# → 日本郵便株式会社

# Get the invoice registration number for a corporation
curl "https://corporation.teraren.com/corporations/1070001005817/text/invoice_registration_number/registrated_number"
# → T1070001005817
```

## API Overview

Base URL: `https://corporation.teraren.com`

All endpoints return JSON when requested with `.json` extension. HTML responses are also available at the same paths without the extension. Responses are cached via Cloudflare CDN for fast global access (~70ms).

### Corporations

- `GET /corporations.json?s={query}&page={n}` — Search corporations by name or 13-digit corporate number
- `GET /corporations/{corporate_number}.json` — Get a single corporation by its 13-digit number
- `GET /corporations/{corporate_number}/text/{attribute}` — Get a single field value as plain text (e.g. `name`, `address`, `post_code`)
- `GET /corporations/{corporate_number}/text/invoice_registration_number/{attribute}` — Get linked invoice registration number field as plain text

### Invoice Registration Numbers

- `GET /invoice_registration_numbers.json?s={query}&page={n}` — Search by name or T-prefixed registration number
- `GET /invoice_registration_numbers/{registrated_number}.json` — Get a single record by T-prefixed number (e.g. `T1234567890123`)
- `GET /invoice_registration_numbers/{registrated_number}/text/{attribute}` — Get a single field value as plain text
- `GET /invoice_registration_numbers/{registrated_number}/text/corporation/{attribute}` — Get linked corporation field as plain text

### EDINET (Listed Companies)

- `GET /edinets.json?s={query}&page={n}` — Search EDINET codes by company name, code, or corporate number
- `GET /edinets/{edinet_code}.json` — Get a single EDINET record by 6-character code

### Prefectures & Areas

- `GET /prefectures.json` — List all 47 prefectures with corporation counts
- `GET /prefectures/{id}.json` — List cities/areas within a prefecture with corporation counts
- `GET /prefectures/{id}/areas/{city_name}` — List corporations in a specific city

### Postcodes

- `GET /postcodes.json?s={query}&page={n}` — Search postcodes
- `GET /postcodes/{code}.json` — Get a single postcode record

## Response Format

All list endpoints return paginated JSON:

```json
{
  "items": [...],
  "pagination": {
    "current_page": 1,
    "previous_page": null,
    "next_page": 2,
    "limit_value": 25,
    "total_pages": 100,
    "total_count": 2500
  }
}
```

### Corporation Fields

- `corporate_number` — 13-digit unique identifier assigned by National Tax Agency
- `name` — Corporation name in Japanese
- `furigana` — Reading in katakana
- `kind` — Entity type (株式会社, 有限会社, etc.)
- `prefecture_name` — Prefecture
- `city_name` — City/ward
- `street_number` — Street address
- `post_code` — Postal code
- `address_outside` — Address outside Japan (if applicable)
- `en_name` — English name
- `process` — Registration process type
- `assignment_date` — Date corporate number was assigned
- `update_date` — Last update date
- `invoice_registration_number` — Linked invoice registration data (if exists)

### Invoice Registration Number Fields

- `registrated_number` — T-prefixed 13-digit number (e.g. T1234567890123)
- `name` — Business name
- `kana` — Reading in katakana
- `address` — Registered address
- `kind` — Entity type
- `registration_date` — Date of registration
- `trade_name` — Trade name (if different from registered name)
- `popular_name_previous_name` — Common/previous names

### EDINET Fields

- `code` — 6-character EDINET code
- `submitter` — Company name
- `submitter_en` — English company name
- `submitter_kana` — Kana reading
- `address` — Address
- `submitter_type` — Type of submitter
- `listed_type` — Listing status
- `capital` — Capital amount
- `securities_code` — Securities code
- `corporate_number` — Linked corporate number

## Documentation

- [API Documentation](https://corporation.teraren.com/doc): Usage guide with cURL examples and sample code
- [OpenAPI 3.0 Specification](https://corporation.teraren.com/doc/redoc): Interactive API reference powered by ReDoc
- [OpenAPI YAML](https://corporation.teraren.com/openapi/corporation.teraren.com.yml): Machine-readable OpenAPI 3.0.3 spec
- [Service Status](https://corporation.betteruptime.com/): Uptime monitoring dashboard

## Terms & Usage

- Free for both personal and commercial use
- No registration or API key required
- No rate limits (CDN-cached responses)
- Data sourced from National Tax Agency public datasets
- Licensed under Creative Commons Attribution-ShareAlike 4.0 International
- [Terms of Service](https://corporation.teraren.com/terms)
- [Privacy Policy](https://corporation.teraren.com/privacy_policy)

## Operator

- Service: 法人くん (Houjin-kun)
- Operator: テラレン合同会社 (Teraren LLC)
- Developer: [@matsubokkuri](https://twitter.com/matsubokkuri)
- Community: [Discord](https://discord.gg/25EPxEerXE)
- Sponsor: [GitHub Sponsors](https://github.com/sponsors/matsubo?frequency=one-time)

## Sister Sites

- [郵便番号検索API](https://postcode.teraren.com/) — Japanese postal code lookup
- [金融機関コードAPI](https://bank.teraren.com/) — Bank/financial institution code lookup
- [駅・路線情報API](https://train.teraren.com/) — Train station and route information