japan-postal-code

JSON / YAML / CSV / XML / Parquet / MessagePack / NDJSON / TOML / Feather / BSON / SQLite | 日本の郵便番号データ、毎月1回更新します | Japan postal code data

Supported Formats

Format	利点 (Advantages)	URL
JSON	日本語: 人間が読みやすく、理解・編集が容易 幅広い言語でサポートされており、ほぼ全てのプログラミング言語にパースライブラリがある 軽量で構造がシンプル API のデータ交換や設定ファイルに適している JavaScript でネイティブサポートされており、フロントエンド開発に親和性が高い English: Human-readable, easy to understand and edit Widely supported, parsing libraries available in almost all programming languages Lightweight with simple structure Suitable for API data exchange and configuration files Native JavaScript support, frontend development friendly	all_data.json
YAML	日本語: 可読性が非常に高く、構文が簡潔で明確 コメントや複数行文字列をサポート 設定ファイルやデータのシリアライズに適している 複雑なデータ構造（リスト、辞書、多層ネスト）をサポート JSON よりも手動編集の場面に適している English: Excellent readability with concise and clear syntax Supports comments and multi-line strings Suitable for configuration files and data serialization Supports complex data structures (lists, dictionaries, multi-level nesting) More suitable for manual editing scenarios than JSON	all_data.yaml
CSV	日本語: フォーマットがシンプルで、理解・使用が容易 Excel などのスプレッドシートソフトウェアで直接サポート ファイルサイズが小さく、大量のデータに適している テキスト形式で、任意のテキストエディタで開ける データのインポート・エクスポートシーンで広く使用されている English: Simple format, easy to understand and use Directly supported by spreadsheet software like Excel Small file size, suitable for large amounts of data Text format, can be opened with any text editor Widely used in data import/export scenarios	all_data.csv
XML	日本語: 構造化度が高く、複雑な階層関係をサポート 自己記述性があり、カスタムタグを定義可能 名前空間と Schema 検証をサポート エンタープライズシステムやデータ交換で広く使用されている 豊富な標準とツールサポート English: Highly structured, supports complex hierarchical relationships Self-descriptive, can define custom tags Supports namespaces and Schema validation Widely used in enterprise systems and data exchange Rich standards and tool support	all_data.xml
Parquet	日本語: 列指向ストレージフォーマットで、クエリと圧縮の効率が非常に高い 自動圧縮により、ファイルサイズが小さい（通常 CSV より 10-100 倍小さい） フィールドレベルの統計情報とインデックスをサポート ビッグデータ分析やデータウェアハウスシーンに適している 言語横断的な互換性（Python, R, Java, Spark など） English: Columnar storage format with extremely high query and compression efficiency Automatic compression results in small file size (typically 10-100x smaller than CSV) Supports field-level statistics and indexes Suitable for big data analysis and data warehouse scenarios Cross-language compatibility (Python, R, Java, Spark, etc.)	all_data.parquet
MessagePack	日本語: バイナリ形式で、ファイルサイズが JSON より 20-30% 小さい シリアライズ/デシリアライズの速度が非常に速い より多くのデータ型（バイナリ、拡張型など）をサポート 言語横断的な互換性 ネットワーク転送や高性能シーンに適している English: Binary format with file size 20-30% smaller than JSON Extremely fast serialization/deserialization Supports more data types (binary, extended types, etc.) Cross-language compatibility Suitable for network transmission and high-performance scenarios	all_data.msgpack
NDJSON (JSONL)	日本語: 1行に1つの JSON オブジェクトで、ストリーミング処理をサポート 行単位で読み書きでき、ファイル全体をメモリに読み込む必要がない 超大規模データセット（数GB以上）の処理に適している データの追加が容易で、ファイル末尾に行を追加するだけでよい ログ記録やビッグデータ処理でよく使用される English: One JSON object per line, supports streaming processing Can read/write line by line without loading entire file into memory Suitable for processing very large datasets (several GB or more) Easy to append data, just add lines to the end of the file Commonly used in log recording and big data processing	all_data.ndjson
TOML	日本語: YAML よりも構文がシンプルで明確 型が明確で、パースの曖昧さを減らす 設定ファイル（Rust の Cargo.toml など）に適している 人間が読みやすく、機械解析も容易 YAML の一部のセキュリティ問題を回避 English: Simpler and clearer syntax than YAML Explicit types reduce parsing ambiguity Suitable for configuration files (e.g., Rust's Cargo.toml) Human-readable and easy for machines to parse Avoids some security issues with YAML	all_data.toml
Feather	日本語: Apache Arrow 形式で、メモリマッピング読み込みにより速度が非常に速い ゼロコピー読み込みで、シリアライズ/デシリアライズが不要 言語横断的な相互運用性（Python、R、Julia など） データ型情報を保持 データサイエンスや分析ワークフローに適している English: Apache Arrow format with extremely fast memory-mapped reading Zero-copy reading without serialization/deserialization Cross-language interoperability (Python, R, Julia, etc.) Preserves data type information Suitable for data science and analysis workflows	all_data.feather
BSON	日本語: バイナリ JSON で、JSON の全ての利点を保持 ファイルサイズが JSON より小さい より多くのデータ型（日付、バイナリ、正規表現など）をサポート MongoDB のネイティブ形式で、クエリとインデックスの効率が高い データベースストレージやネットワーク転送に適している English: Binary JSON that retains all advantages of JSON Smaller file size than JSON Supports more data types (dates, binary, regular expressions, etc.) MongoDB's native format with efficient queries and indexes Suitable for database storage and network transmission	all_data.bson
SQLite	日本語: ファイルベースのデータベースで、独立したサーバーが不要 SQL クエリをサポートし、インデックスを作成してクエリを高速化できる ACID 特性により、データ整合性が保証される 軽量（コアライブラリは数百KBのみ） アプリケーション組み込みデータベースやデータ分析に適している English: File-based database, no separate server required Supports SQL queries, can create indexes to speed up queries ACID properties ensure data integrity Lightweight (core library is only several hundred KB) Suitable for embedded databases in applications and data analysis	all_data.db

グループ化データ構造 / Grouped Data Structure

概要 / Overview

日本語: データは郵便番号の前3桁でグループ化され、階層的なファイル構造で提供されています。これにより、単一ファイルのサイズを削減し、特定の地域のデータを効率的に取得できます。

English: Data is grouped by the first 3 digits of postal codes and provided in a hierarchical file structure. This reduces the size of individual files and allows efficient retrieval of data for specific regions.

ファイル構造 / File Structure

datasets/
├── 176.json          # 176で始まる全ての郵便番号の完全なレコードリスト
│                     # All postal codes starting with 176
├── 176/
│   ├── 0005.json     # 郵便番号 1760005 の完全なレコード
│   │                 # Complete record for postal code 1760005
│   ├── 0006.json     # 郵便番号 1760006 の完全なレコード
│   │                 # Complete record for postal code 1760006
│   └── ...
├── 177.json
├── 177/
│   └── ...
└── ...

注意 / Note:

• グループ化されたデータは JSON 形式のみ で提供されています
• Grouped data is only available in JSON format
• 全データセット（all_data.*）は全てのフォーマットで利用可能です
• Full datasets (all_data.*) are available in all formats

データ取得方法 / How to Retrieve Data

方法1: 前3桁でグループ全体を取得 / Method 1: Get All Records by Prefix

日本語: 特定の地域（前3桁）の全ての郵便番号データを取得する場合：

例: 176で始まる全ての郵便番号を取得

// JavaScript の例
fetch('https://stayforge.github.io/japan-postal-code/datasets/176.json')
  .then(response => response.json())
  .then(data => {
    // data は 176 で始まる全ての郵便番号の配列
    console.log(data);
  });

# Python の例
import requests
import json

response = requests.get('https://stayforge.github.io/japan-postal-code/datasets/176.json')
data = response.json()
# data は 176 で始まる全ての郵便番号のリスト

English: To retrieve all postal code data for a specific region (first 3 digits):

Example: Get all postal codes starting with 176

// JavaScript example
fetch('https://stayforge.github.io/japan-postal-code/datasets/176.json')
  .then(response => response.json())
  .then(data => {
    // data is an array of all postal codes starting with 176
    console.log(data);
  });

# Python example
import requests
import json

response = requests.get('https://stayforge.github.io/japan-postal-code/datasets/176.json')
data = response.json()
# data is a list of all postal codes starting with 176

方法2: 特定の郵便番号を直接取得 / Method 2: Get Specific Postal Code

日本語: 完全な7桁の郵便番号が分かっている場合、直接そのファイルを取得できます：

例: 郵便番号 1760005 を取得

// JavaScript の例
fetch('https://stayforge.github.io/japan-postal-code/datasets/176/0005.json')
  .then(response => response.json())
  .then(data => {
    // data は 1760005 の郵便番号データ（単一オブジェクトまたは配列）
    console.log(data);
  });

# Python の例
import requests

# 郵便番号を分割
postal_code = "1760005"
prefix = postal_code[:3]  # "176"
suffix = postal_code[3:]  # "0005"

url = f'https://stayforge.github.io/japan-postal-code/datasets/{prefix}/{suffix}.json'
response = requests.get(url)
data = response.json()
# data は 1760005 の郵便番号データ

English: If you know the complete 7-digit postal code, you can directly retrieve that file:

Example: Get postal code 1760005

// JavaScript example
fetch('https://stayforge.github.io/japan-postal-code/datasets/176/0005.json')
  .then(response => response.json())
  .then(data => {
    // data is the postal code data for 1760005 (single object or array)
    console.log(data);
  });

# Python example
import requests

# Split postal code
postal_code = "1760005"
prefix = postal_code[:3]  # "176"
suffix = postal_code[3:]  # "0005"

url = f'https://stayforge.github.io/japan-postal-code/datasets/{prefix}/{suffix}.json'
response = requests.get(url)
data = response.json()
# data is the postal code data for 1760005

利点 / Advantages

日本語:

• ファイルサイズの削減: 単一の大きなファイルではなく、小さなファイルに分割されるため、必要なデータのみをダウンロードできます
• 高速な取得: 特定の地域や郵便番号のデータを直接取得できるため、全体を読み込む必要がありません
• 帯域幅の節約: 必要なデータのみを取得することで、ネットワーク帯域幅を節約できます
• キャッシュ効率: 小さなファイルはブラウザやCDNでキャッシュしやすく、再取得が高速です
• GitHub Pages との互換性: 静的ファイルホスティングに最適化されており、GitHub Pages で直接提供できます

English:

• Reduced File Size: Data is split into smaller files instead of one large file, allowing you to download only the data you need
• Faster Retrieval: You can directly retrieve data for specific regions or postal codes without loading the entire dataset
• Bandwidth Savings: Fetching only the required data saves network bandwidth
• Cache Efficiency: Smaller files are easier to cache in browsers or CDNs, enabling faster subsequent retrievals
• GitHub Pages Compatibility: Optimized for static file hosting and can be directly served via GitHub Pages

対応フォーマット / Supported Formats

日本語: グループ化されたデータは JSON 形式のみ で提供されています。これは、JSON が最も広くサポートされており、Web アプリケーションでの使用に最適なためです。

全データセット（all_data.*）は、JSON, YAML, CSV, XML, Parquet, MessagePack, NDJSON, TOML, Feather, BSON, SQLite の全てのフォーマットで利用可能です。

English: Grouped data is only available in JSON format. This is because JSON has the widest support and is optimal for use in web applications.

Full datasets (all_data.*) are available in all formats: JSON, YAML, CSV, XML, Parquet, MessagePack, NDJSON, TOML, Feather, BSON, SQLite.

例 / Examples:

• https://stayforge.github.io/japan-postal-code/datasets/176.json ✅
• https://stayforge.github.io/japan-postal-code/datasets/176/0005.json ✅
• https://stayforge.github.io/japan-postal-code/datasets/176.yaml ❌ (グループ化データでは利用不可 / Not available in grouped data)
• https://stayforge.github.io/japan-postal-code/datasets/all_data.yaml ✅ (全データセットでは利用可能 / Available in full dataset)

著作権 / Copyright

日本語: 本プロジェクトで提供されている郵便番号データの著作権は、日本郵便株式会社（Japan Post）に帰属します。本プロジェクトは、日本郵便が提供する公式データに対して、データの分割とクリーンアップ（整理）のみを行っており、データの内容自体は変更していません。

English: The copyright of the postal code data provided in this project belongs to Japan Post Co., Ltd. This project only performs data splitting and cleaning (organization) on the official data provided by Japan Post, and does not modify the content of the data itself.