{"_id":"@47stats/api","name":"@47stats/api","dist-tags":{"latest":"0.9.0"},"versions":{"0.9.0":{"name":"@47stats/api","description":"47都道府県統計データAPIのTypeScriptクライアントライブラリ","version":"0.9.0","author":{"name":"team 47stats"},"bugs":{"url":"https://github.com/47stats/47stats-api/issues"},"devDependencies":{"@types/geojson":"^7946.0.15","@types/node":"^22.10.1","@typescript-eslint/eslint-plugin":"^8.41.0","@typescript-eslint/parser":"^8.41.0","dotenv":"^17.2.3","eslint":"^9.34.0","prettier":"^3.6.2","typescript":"^5.6.2","vite":"^6.0.1","vite-plugin-dts":"^4.3.0","vitest":"^2.1.8"},"engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/index.js","require":"./dist/index.umd.cjs"}},"homepage":"https://47stats-api.com","keywords":["47stats","47stats-api","typescript"],"license":"MIT","main":"dist/index.umd.cjs","module":"dist/index.js","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/47stats/47stats-api.git"},"scripts":{"build":"vite build && npm run types:build","build:watch":"vite build --watch","coverage":"vitest run --coverage","dev":"vite","format":"prettier --write \"src/**/*.{js,jsx,ts,tsx,json,css,scss,md}\"","format:check":"prettier --check \"src/**/*.{js,jsx,ts,tsx,json,css,scss,md}\"","lint":"eslint \"src/**/*.{js,jsx,ts,tsx}\"","lint:fix":"eslint \"src/**/*.{js,jsx,ts,tsx}\" --fix","npm:pack":"npm pack","preview":"vite preview","test":"vitest --mode test","test:watch":"vitest --watch --mode test","type-check":"tsc --noEmit","types:build":"tsc -p tsconfig.lib.json"},"type":"module","types":"dist/types/index.d.ts","gitHead":"8b7211dd411945ac000dd96e40ee8f569e0f2734","_id":"@47stats/api@0.9.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-4i7P0+nUcQigNYZU0j6aK94surKdcZeS349f47Nnw7aBExvh83hXZ1mpwGUzKh7+0l82cRJvn3x+ayT6b4cehw==","shasum":"99226aaab74eb7816d999bf1b7e1a688742b966c","tarball":"https://registry.npmjs.org/@47stats/api/-/api-0.9.0.tgz","fileCount":31,"unpackedSize":71085,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDPpItBfD3djnhkvxxt92t6sFrm7VD5ORL0KuVPinUWBAIhAPj6R7529nyS5Krsojd1HBj02vq2aiwkVTr4uzWl80dh"}]},"_npmUser":{"name":"47stats","email":"47stats@nihon-toukei.co.jp"},"directories":{},"maintainers":[{"name":"47stats","email":"47stats@nihon-toukei.co.jp"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/api_0.9.0_1784621788674_0.12751018106920542"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-21T08:16:28.448Z","0.9.0":"2026-07-21T08:16:28.885Z","modified":"2026-07-21T08:16:29.125Z"},"maintainers":[{"name":"47stats","email":"47stats@nihon-toukei.co.jp"}],"description":"47都道府県統計データAPIのTypeScriptクライアントライブラリ","homepage":"https://47stats-api.com","keywords":["47stats","47stats-api","typescript"],"repository":{"type":"git","url":"git+https://github.com/47stats/47stats-api.git"},"author":{"name":"team 47stats"},"bugs":{"url":"https://github.com/47stats/47stats-api/issues"},"license":"MIT","readme":"# @47stats/api\r\n\r\n[![npm version](https://badge.fury.io/js/@47stats%2F47stats-api.svg)](https://badge.fury.io/js/@47stats%2F47stats-api)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\r\n[![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)\r\n\r\n47都道府県統計データAPIの公式TypeScriptクライアントライブラリです。日本の統計データを簡単にアクセス・活用できるよう設計されています。\r\n\r\n## 特徴\r\n\r\n- **型安全**: TypeScriptによる完全な型定義とIntelliSenseサポート\r\n- **高性能**: 自動リトライ・メモリキャッシュ・大容量データ分割取得\r\n- **堅牢性**: 包括的エラーハンドリングとデバッグ機能\r\n- **包括的API**: 認証、カタログ、統計、地図、領域生成の全機能\r\n- **開発者フレンドリー**: モダンなビルドツール（Vite、ESLint、Prettier、Vitest）\r\n- **軽量**: 15.57 kB (gzipped: 3.21 kB)\r\n\r\n## インストール\r\n\r\n```bash\r\n# npm\r\nnpm install @47stats/api\r\n\r\n# yarn\r\nyarn add @47stats/api\r\n\r\n# pnpm\r\npnpm add @47stats/api\r\n```\r\n\r\n## クイックスタート\r\n\r\n### 環境設定\r\n\r\n```typescript\r\nimport { APIEnv } from '@47stats/api';\r\n\r\n// API認証情報を設定（一度だけ実行）\r\nAPIEnv.API_URL = 'https://your-api-endpoint.com/api/stats/v1';\r\nAPIEnv.API_KEY = 'your-api-key';\r\n```\r\n\r\n### 基本的な使用例\r\n先ずは **カタログ (Catalog)** から利用できるデータベース、ストア、カラム等を探してください。\r\n以下の例は database: \"KOK\", store: \"CITY\" とありますが、ご利用の際はカタログに定義されている database および store を設定してください。\r\n\r\n```typescript\r\nimport { getDatalistList, hitTest, getDatamapPolygon } from '@47stats/api';\r\n\r\n// 例：福岡県の市区町村別人口データを取得\r\nconst populationData = await getDatalistList({\r\n  database: \"KOK\",// データベース指定\r\n  store: \"CITY\",         // 市区町村指定\r\n  column: [\r\n    \"CITY\",              // 市区町村コード\r\n    \"PREFNAME\",          // 都道府県名\r\n    \"CITYNAME\",          // 市区町村名\r\n    \"N1\",                // 総人口\r\n    \"N3\",                // 男性人口\r\n    \"N5\"                 // 女性人口\r\n  ],\r\n  area: \"40\"             // 福岡県\r\n});\r\n\r\n// 例：座標から地域情報を取得（逆ジオコーディング）\r\nconst locationInfo = await hitTest({ \r\n  lon: 139.767, \r\n  lat: 35.683,\r\n  database: 'KOK' \r\n});\r\nconsole.log(locationInfo.prefname); // \"東京都\"\r\nconsole.log(locationInfo.cityname); // \"千代田区\"\r\n\r\n// 地図データをGeoJSON形式で取得\r\nconst mapData = await getDatamapPolygon({\r\n  database: \"KOK\",\r\n  store: \"CITY\",\r\n  column: [\"N1\"],        // 人口データ\r\n  area: \"13\",            // 東京都\r\n  simplify: true         // 形状簡略化\r\n});\r\n```\r\n\r\n## 主要機能\r\n\r\n### 認証\r\n```typescript\r\nimport { getToken } from '@47stats/api';\r\n\r\n// API認証トークンを取得\r\nconst authInfo = await getToken();\r\nconsole.log(`認証期限: ${authInfo.limit}`);\r\n```\r\n\r\n### 統計データ取得\r\n\r\n#### データリスト取得\r\n```typescript\r\nimport { getDatalistList, getDatalistCount } from '@47stats/api';\r\n\r\n// データ件数を確認\r\nconst count = await getDatalistCount({\r\n  database: \"KOK\",\r\n  store: \"CITY\",\r\n  area: \"40\"\r\n});\r\n\r\n// ページング付きでデータを取得\r\nconst dataList = await getDatalistList({\r\n  database: \"KOK\",\r\n  store: \"CITY\", \r\n  column: [\"CITY\", \"DNAME\", \"N1\", \"N3\", \"N5\"],\r\n  area: \"40\",\r\n  start: 0,\r\n  limit: 10\r\n});\r\n```\r\n\r\n#### 統計サマリー\r\n```typescript\r\nimport { getAverage, getMax, getMin, getTotal, getStdev } from '@47stats/api';\r\n\r\nconst params = {\r\n  database: \"KOK\",\r\n  store: \"CITY\",\r\n  column: [\"N1\", \"N3\", \"N5\"],\r\n  area: \"40\"\r\n};\r\n\r\n// 各種統計値を取得\r\nconst average = await getAverage(params);    // 平均値\r\nconst maximum = await getMax(params);        // 最大値\r\nconst minimum = await getMin(params);        // 最小値\r\nconst total = await getTotal(params);        // 合計値\r\nconst stdev = await getStdev(params);        // 標準偏差\r\n```\r\n\r\n#### ランキング分析\r\n```typescript\r\nimport { getRankAvg, getFrequency, getRange } from '@47stats/api';\r\n\r\nconst rankParams = {\r\n  database: \"KOK\",\r\n  store: \"CITY\",\r\n  column: \"N1\",\r\n  area: \"40\"\r\n};\r\n\r\n// 平均値によるランク分析\r\nconst rankAvg = await getRankAvg(rankParams);\r\n\r\n// 件数均等分割（7段階）\r\nconst frequency = await getFrequency({ \r\n  ...rankParams, \r\n  division: 7 \r\n});\r\n\r\n// 数値範囲均等分割（5段階）\r\nconst range = await getRange({ \r\n  ...rankParams, \r\n  division: 5 \r\n});\r\n```\r\n\r\n### 地図データ（GeoJSON）\r\n\r\n```typescript\r\nimport { getDatamapPoint, getDatamapPolygon } from '@47stats/api';\r\n\r\nconst mapParams = {\r\n  database: \"KOK\",\r\n  store: \"CITY\",\r\n  column: [\"N1\", \"N3\", \"N5\"],\r\n  area: \"13101\",  // 千代田区\r\n  simplify: true\r\n};\r\n\r\n// ポイントデータ取得\r\nconst pointData = await getDatamapPoint(mapParams);\r\n\r\n// ポリゴンデータ取得 \r\nconst polygonData = await getDatamapPolygon(mapParams);\r\n\r\n// Leaflet.jsやMapbox GLなどの地図ライブラリで直接利用可能\r\n```\r\n\r\n### カタログ情報\r\n\r\n```typescript\r\nimport { \r\n  getDatabaseList, \r\n  getAreaList, \r\n  getColumnList,\r\n  getStoreList \r\n} from '@47stats/api';\r\n\r\n// 利用可能なデータベース一覧\r\nconst databases = await getDatabaseList({});\r\n\r\n// エリア情報（都道府県、市区町村、町丁）\r\nconst areas = await getAreaList({\r\n  database: \"KOK\",\r\n  store: \"PREF\"  // または \"CITY\", \"TOWN\"\r\n});\r\n\r\n// データ列情報\r\nconst columns = await getColumnList({\r\n  database: \"KOK\", \r\n  store: \"CITY\",\r\n  limit: 50\r\n});\r\n\r\n// データストア情報\r\nconst stores = await getStoreList({\r\n  database: \"KOK\"\r\n});\r\n```\r\n\r\n### 領域生成\r\n\r\n```typescript\r\nimport { getCircle, getDonut } from '@47stats/api';\r\n\r\n// 円形領域（半径3km）\r\nconst circle = await getCircle({\r\n  longitude: 130.882741,\r\n  latitude: 33.882006,\r\n  radius: 3000\r\n});\r\n\r\n// ドーナツ領域（外径1km、内径500m）\r\nconst donut = await getDonut({\r\n  longitude: 130.882741,\r\n  latitude: 33.882006,\r\n  outer: 1000,\r\n  inner: 500\r\n});\r\n```\r\n\r\n### 座標・領域による検索\r\n\r\n#### 座標指定\r\n```typescript\r\n// 座標による検索\r\nconst result = await getDatalistList({\r\n  database: \"KOK\",\r\n  store: \"CITY\", \r\n  column: [\"CITY\", \"DNAME\", \"N1\"],\r\n  lonlat: [139.767, 35.683]  // 経度、緯度\r\n});\r\n\r\n// Point GeoJSONによる検索\r\nconst point = {\r\n  type: 'Point',\r\n  coordinates: [139.767, 35.683]\r\n};\r\nconst result2 = await getDatalistList({\r\n  database: \"KOK\",\r\n  store: \"CITY\",\r\n  column: [\"CITY\", \"DNAME\", \"N1\"],\r\n  point: JSON.stringify(point)\r\n});\r\n```\r\n\r\n#### ポリゴン領域指定\r\n```typescript\r\nconst polygon = {\r\n  type: 'Polygon',\r\n  coordinates: [[[\r\n    [130.881618, 33.883977],\r\n    [130.881049, 33.881901], \r\n    [130.884321, 33.88118],\r\n    [130.884879, 33.883326],\r\n    [130.881618, 33.883977]\r\n  ]]]\r\n};\r\n\r\nconst result = await getDatalistList({\r\n  database: \"KOK\",\r\n  store: \"CITY\",\r\n  column: [\"CITY\", \"DNAME\", \"N1\"],\r\n  polygon: JSON.stringify(polygon)\r\n});\r\n```\r\n\r\n## API関数リファレンス\r\n\r\nすべての実装済みAPI関数の完全なリスト：\r\n\r\n### 認証 (Auth)\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getToken()` | APIキーから認証トークンを取得 | `Promise<AuthType>` |\r\n\r\n### カタログ (Catalog)\r\n\r\n#### Database\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getDatabaseList(props)` | データベース一覧を取得 | `Promise<DatabaseType[]>` |\r\n| `getDatabaseInfo(props)` | データベース情報を取得 | `Promise<DatabaseType>` |\r\n| `getDatabaseCount(props)` | データベース件数を取得 | `Promise<number>` |\r\n\r\n#### Store\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getStoreList(props)` | データストア一覧を取得 | `Promise<StoreType[]>` |\r\n| `getStoreInfo(props)` | データストア情報を取得 | `Promise<StoreType>` |\r\n| `getStoreCount(props)` | データストア件数を取得 | `Promise<number>` |\r\n| `getStoreClass(props)` | ストア分類一覧を取得 | `Promise<StoreClassType[]>` |\r\n\r\n#### Area\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getAreaList(props)` | エリア一覧を取得 | `Promise<AreaInfoType[]>` |\r\n| `getAreaInfo(props)` | エリア情報を取得 | `Promise<AreaInfoType>` |\r\n| `getAreaCount(props)` | エリア件数を取得 | `Promise<number>` |\r\n| `getAreaClass(props)` | エリア分類一覧を取得 | `Promise<AreaClassType[]>` |\r\n\r\n#### Column\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getColumnList(props)` | 列一覧を取得 | `Promise<ColumnInfoType[]>` |\r\n| `getColumnInfo(props)` | 列情報を取得 | `Promise<ColumnInfoType>` |\r\n| `getColumnCount(props)` | 列件数を取得 | `Promise<number>` |\r\n| `getColumnClass(props)` | 列分類一覧を取得 | `Promise<ColumnClassType[]>` |\r\n| `getColumnKindList(props)` | 列種別一覧を取得 | `Promise<ColumnKindType[]>` |\r\n| `getColumnKindCount(props)` | 列種別件数を取得 | `Promise<number>` |\r\n\r\n### 統計データ (Stats)\r\n\r\n#### Datalist\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getDatalistList(props)` | 統計データリストを取得 | `Promise<Json[]>` |\r\n| `getDatalistRow(props)` | 統計データ1行を取得 | `Promise<Json>` |\r\n| `getDatalistCount(props)` | 統計データ件数を取得 | `Promise<number>` |\r\n\r\n#### Group（領域内集計）\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getGroupCircle(props)` | 円形領域内の集約データを取得 | `Promise<Json>` |\r\n| `getGroupPolygon(props)` | 任意領域内の集約データを取得 | `Promise<Json>` |\r\n\r\n#### Rank（ランク分析）\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getRankAvg(props)` | 平均値によるランク分析 | `Promise<RankType[]>` |\r\n| `getFrequency(props)` | 該当件数均等分割ランク | `Promise<RankType[]>` |\r\n| `getRange(props)` | 数値範囲均等分割ランク | `Promise<RankType[]>` |\r\n\r\n#### Summary（統計サマリー）\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getCount(props)` | 件数を取得 | `Promise<SummaryType>` |\r\n| `getMin(props)` | 最小値を取得 | `Promise<SummaryType>` |\r\n| `getMax(props)` | 最大値を取得 | `Promise<SummaryType>` |\r\n| `getAverage(props)` | 平均値を取得 | `Promise<SummaryType>` |\r\n| `getTotal(props)` | 合計値を取得 | `Promise<SummaryType>` |\r\n| `getStdev(props)` | 標準偏差を取得 | `Promise<SummaryType>` |\r\n\r\n### 地図データ (Map)\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getDatamapPoint(props)` | ポイントデータをGeoJSON形式で取得 | `Promise<FeatureCollection>` |\r\n| `getDatamapPolygon(props)` | ポリゴンデータをGeoJSON形式で取得 | `Promise<FeatureCollection>` |\r\n\r\n### 領域生成 (Feature)\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `getCircle(props)` | 円形領域を生成 | `Promise<Polygon>` |\r\n| `getDonut(props)` | ドーナツ領域を生成 | `Promise<Polygon>` |\r\n\r\n### ユーティリティ (Utils)\r\n\r\n| 関数名 | 説明 | 戻り値 |\r\n|--------|------|--------|\r\n| `hitTest(props)` | 座標から地域情報を取得（逆ジオコーディング） | `Promise<HitInfoType>` |\r\n\r\n### 低レベルAPI\r\n\r\n| 関数名 | 説明 | パラメータ |\r\n|--------|------|-----------|\r\n| `fetchData<T>(url, params?, name?, onError?, retry?, retryDelay?, cacheTTL?, logger?)` | 汎用APIリクエスト関数 | 詳細なエラーハンドリングとキャッシュ制御 |\r\n| `fetchOverlimitList<T>(url, params, count, name?)` | 大容量データの自動分割取得 | 件数制限を超えるデータを自動分割 |\r\n| `fetchOverlimitOne<T>(url, params, name?)` | 大容量単一レコード取得 | 列数制限対応 |\r\n\r\n---\r\n\r\n## 高度な機能\r\n\r\n### エラーハンドリング\r\n\r\n```typescript\r\nimport { fetchData, APIError } from '@47stats/api';\r\n\r\ntry {\r\n  const data = await fetchData(\r\n    '/stats/summary/average',\r\n    JSON.stringify(params),\r\n    'average',\r\n    (error: APIError) => {\r\n      // カスタムエラーハンドラー\r\n      console.error('API Error:', error.message);\r\n      console.error('Status Code:', error.status);\r\n      console.error('Response Data:', error.responseData);\r\n      \r\n      // エラー通知システムと連携\r\n      notificationSystem.error(error.message);\r\n    }\r\n  );\r\n} catch (error) {\r\n  if (error instanceof APIError) {\r\n    // APIエラーの詳細処理\r\n    switch (error.status) {\r\n      case 400:\r\n        console.error('リクエストパラメータが不正です');\r\n        break;\r\n      case 401: \r\n        console.error('認証が必要です');\r\n        break;\r\n      case 429:\r\n        console.error('APIレート制限に達しました');\r\n        break;\r\n      default:\r\n        console.error('予期しないAPIエラーが発生しました');\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### キャッシュとパフォーマンス\r\n\r\n```typescript\r\nconst data = await fetchData(\r\n  url,\r\n  params,\r\n  name,\r\n  onError,\r\n  3,        // リトライ回数（デフォルト: 3）\r\n  1000,     // リトライ間隔（ミリ秒、デフォルト: 500）\r\n  600000,   // キャッシュTTL（ミリ秒、デフォルト: 300000=5分）\r\n  console.log // カスタムロガー\r\n);\r\n\r\n// 大容量データの自動分割取得\r\nconst largeDataset = await getDatalistList({\r\n  database: \"KOK\",\r\n  store: \"TOWN\",\r\n  column: [\"TOWN\", \"DNAME\", \"N1\", \"N3\", \"N5\"],\r\n  area: \"13\"      // 東京都全域\r\n  // limitを指定しない場合、全データを自動分割して取得\r\n});\r\n```\r\n\r\n## 開発環境\r\n\r\n### 必要要件\r\n- **Node.js**: 18.0.0以上\r\n- **TypeScript**: 5.6.2以上\r\n- **Modern Browser**: ES2020対応\r\n\r\n### ローカル開発\r\n\r\n```bash\r\n# リポジトリクローン\r\ngit clone https://github.com/47stats/47stats-api.git\r\ncd 47stats-api\r\n\r\n# 依存関係インストール\r\nnpm install\r\n\r\n# 環境変数設定\r\ncp .env.example .env\r\n# .envファイルを編集してAPI認証情報を設定\r\n```\r\n\r\n### 環境変数設定\r\n\r\n`.env`ファイルを作成し、以下を設定：\r\n\r\n```env\r\n# API設定\r\nVITE_STATS_API_URL=https://your-api-endpoint.com/api/stats/v1\r\nVITE_STATS_API_KEY=your-api-key\r\n```\r\n\r\n### 開発コマンド\r\n\r\n```bash\r\n# 開発サーバー起動\r\nnpm run dev\r\n\r\n# プロダクションビルド\r\nnpm run build\r\n\r\n# 型定義生成\r\nnpm run types:build\r\n\r\n# パッケージング確認\r\nnpm run npm:pack\r\n\r\n# リアルタイム開発\r\nnpm run build:watch\r\n\r\n# 開発用プレビュー\r\nnpm run preview\r\n```\r\n\r\n### コード品質\r\n\r\n```bash\r\n# テスト実行\r\nnpm run test           # 全テスト\r\nnpm run test:watch     # ウォッチモード  \r\nnpm run coverage       # カバレッジ測定\r\n\r\n# コード品質チェック\r\nnpm run lint           # ESLint実行\r\nnpm run lint:fix       # 自動修正\r\nnpm run format         # Prettier整形\r\nnpm run format:check   # フォーマット確認\r\nnpm run type-check     # TypeScript型チェック\r\n```\r\n\r\n## テスト\r\n\r\n包括的なテストスイートによる品質保証：\r\n\r\n```bash\r\n# 全テスト実行\r\nnpm run test\r\n\r\n# ウォッチモードでテスト\r\nnpm run test:watch\r\n\r\n# カバレッジレポート生成\r\nnpm run coverage\r\n```\r\n\r\n### テスト例\r\n\r\n```typescript\r\n// src/__test__/stats/datalist.test.ts\r\nimport { describe, expect, test } from 'vitest';\r\nimport { getDatalistList, getDatalistCount } from '../../';\r\n\r\ndescribe('stats/datalist', () => {\r\n  test('データリスト取得テスト', async () => {\r\n    const result = await getDatalistList({\r\n      database: 'KOK',\r\n      store: 'CITY',\r\n      column: ['CITY', 'DNAME', 'N1'],\r\n      area: '40',\r\n      start: 0,\r\n      limit: 5\r\n    });\r\n    \r\n    expect(result).toBeDefined();\r\n    expect(Array.isArray(result)).toBe(true);\r\n    expect(result.length).toBeGreaterThan(0);\r\n  });\r\n});\r\n```\r\n\r\n## プロジェクト構成\r\n\r\n```\r\nsrc/\r\n├── auth/              # 認証機能\r\n│   └── auth.ts        \r\n├── catalog/           # カタログ操作  \r\n│   ├── area.ts        # エリア情報\r\n│   ├── column.ts      # 列情報\r\n│   ├── database.ts    # データベース情報\r\n│   └── store.ts       # ストア情報\r\n├── feature/           # 領域生成\r\n│   ├── circle.ts      # 円形領域\r\n│   └── donut.ts       # ドーナツ領域  \r\n├── map/               # 地図データ\r\n│   └── datamap.ts     # GeoJSON取得\r\n├── stats/             # 統計データ\r\n│   ├── datalist.ts    # データリスト\r\n│   ├── group.ts       # グループ集計\r\n│   ├── rank.ts        # ランキング\r\n│   └── summary.ts     # 統計サマリー\r\n├── utils/             # ユーティリティ\r\n│   └── hit-test.ts    # 座標→地域情報変換\r\n├── __test/            # テストファイル\r\n├── base.ts            # 基本型定義\r\n├── env.ts             # 環境設定\r\n├── fetchdata.ts       # API通信コア\r\n├── fetch-overlimit.ts # 大容量データ処理\r\n├── json.ts            # JSON型定義\r\n└── test-setup.ts      # テスト環境設定\r\n```\r\n\r\n## 使用例・応用\r\n\r\n### Webアプリケーション統合\r\n\r\n```typescript\r\n// React/Vue.js での使用例\r\nimport { useEffect, useState } from 'react';\r\nimport { getDatalistList, getDatamapPolygon } from '@47stats/api';\r\n\r\nfunction PopulationMap({ prefecture = \"40\" }) {\r\n  const [mapData, setMapData] = useState(null);\r\n  const [loading, setLoading] = useState(true);\r\n\r\n  useEffect(() => {\r\n    const fetchMapData = async () => {\r\n      try {\r\n        const data = await getDatamapPolygon({\r\n          database: \"KOK\",\r\n          store: \"CITY\", \r\n          column: [\"N1\"], // 人口データ\r\n          area: prefecture,\r\n          simplify: true\r\n        });\r\n        setMapData(data);\r\n      } catch (error) {\r\n        console.error('地図データの取得に失敗:', error);\r\n      } finally {\r\n        setLoading(false);\r\n      }\r\n    };\r\n\r\n    fetchMapData();\r\n  }, [prefecture]);\r\n\r\n  if (loading) return <div>読み込み中...</div>;\r\n  \r\n  // Leaflet/Mapbox GL JS等でmapDataを描画\r\n  return <MapComponent data={mapData} />;\r\n}\r\n```\r\n\r\n### データ分析・可視化\r\n\r\n```typescript\r\n// D3.js/Chart.js との連携例\r\nimport { getRankAvg, getFrequency } from '@47stats/api';\r\n\r\nasync function createRankingChart(prefecture: string) {\r\n  // ランキングデータ取得\r\n  const rankData = await getFrequency({\r\n    database: \"KOK\",\r\n    store: \"CITY\",\r\n    column: \"N1\",\r\n    area: prefecture,\r\n    division: 7\r\n  });\r\n\r\n  // Chart.jsでヒストグラム描画\r\n  const chartData = {\r\n    labels: rankData.map((item, i) => `ランク${i + 1}`),\r\n    datasets: [{\r\n      label: '市区町村数',\r\n      data: rankData.map(item => item.count),\r\n      backgroundColor: 'rgba(54, 162, 235, 0.5)'\r\n    }]\r\n  };\r\n\r\n  return new Chart(ctx, {\r\n    type: 'bar',\r\n    data: chartData\r\n  });\r\n}\r\n```\r\n\r\n### Node.js サーバーサイド\r\n\r\n```typescript\r\n// Express.js APIサーバー例\r\nimport express from 'express';\r\nimport { getDatalistList, hitTest } from '@47stats/api';\r\n\r\nconst app = express();\r\n\r\n// 座標から地域情報取得API\r\napp.get('/api/location/:lon/:lat', async (req, res) => {\r\n  try {\r\n    const { lon, lat } = req.params;\r\n    const locationInfo = await hitTest({ \r\n      lon: parseFloat(lon), \r\n      lat: parseFloat(lat),\r\n      database: 'KOK'\r\n    });\r\n    res.json(locationInfo);\r\n  } catch (error) {\r\n    res.status(500).json({ error: error.message });\r\n  }\r\n});\r\n\r\n// 統計データ検索API  \r\napp.post('/api/stats', async (req, res) => {\r\n  try {\r\n    const data = await getDatalistList(req.body);\r\n    res.json(data);\r\n  } catch (error) {\r\n    res.status(500).json({ error: error.message });\r\n  }\r\n});\r\n```\r\n\r\n## TypeScript設定\r\n\r\nプロジェクトは厳密なTypeScript設定を採用：\r\n\r\n```json\r\n// tsconfig.json（抜粋）\r\n{\r\n  \"compilerOptions\": {\r\n    \"strict\": true,\r\n    \"noUncheckedIndexedAccess\": true,\r\n    \"target\": \"ES2020\",\r\n    \"module\": \"ESNext\", \r\n    \"moduleResolution\": \"node\",\r\n    \"esModuleInterop\": true\r\n  }\r\n}\r\n```\r\n\r\n### 型定義例\r\n\r\n```typescript\r\n// 完全な型サポート\r\nimport type { \r\n  DatalistListProps,\r\n  AreaInfoType,\r\n  HitInfoType,\r\n  SummaryType,\r\n  RankType \r\n} from '@47stats/api';\r\n\r\n// 型安全なパラメータ構築\r\nconst params: DatalistListProps = {\r\n  database: \"KOK\",     // 文字列リテラル型\r\n  store: \"CITY\",       // \"CITY\" | \"PREF\" | \"TOWN\"\r\n  column: [\"N1\", \"N3\"], // string | string[]\r\n  area: \"40\"           // string | string[]\r\n};\r\n```\r\n\r\n## パフォーマンス最適化\r\n\r\n### 自動分割取得\r\n大容量データを自動的に分割して取得：\r\n\r\n```typescript\r\n// 10,000件を超えるデータも自動分割で高速取得\r\nconst allJapanData = await getDatalistList({\r\n  database: \"KOK\",\r\n  store: \"TOWN\",  // 全国の町丁目データ\r\n  column: [\"TOWN\", \"DNAME\", \"N1\"]\r\n  // limitを指定しない = 全データを自動分割取得\r\n});\r\n```\r\n\r\n### メモリキャッシュ\r\n同一リクエストの結果を自動キャッシュ：\r\n\r\n```typescript\r\n// 初回は API 呼び出し\r\nconst data1 = await getDatalistList(params);\r\n\r\n// 2回目以降は キャッシュから高速返却（5分間）\r\nconst data2 = await getDatalistList(params); \r\n```\r\n\r\n### 地図データ最適化\r\n```typescript\r\n// 形状簡略化で軽量化\r\nconst lightMapData = await getDatamapPolygon({\r\n  database: \"KOK\",\r\n  store: \"CITY\",\r\n  area: \"40\",\r\n  simplify: true  // ポリゴン形状を簡略化\r\n});\r\n```\r\n\r\n## 貢献\r\n\r\nコントリビューション歓迎！以下の手順でご参加ください：\r\n\r\n1. **Fork** このリポジトリを Fork\r\n2. **Branch** フィーチャーブランチを作成  \r\n   `git checkout -b feature/amazing-feature`\r\n3. **Commit** 変更をコミット  \r\n   `git commit -m 'Add amazing feature'`\r\n4. **Push** ブランチをプッシュ  \r\n   `git push origin feature/amazing-feature`\r\n5. **Pull Request** を作成\r\n\r\n### 開発ガイドライン\r\n\r\n- **型安全性**: すべてのコードはTypeScriptで型安全である必要があります\r\n- **テストカバレッジ**: 新機能には対応するテストを追加\r\n- **コード品質**: ESLint・Prettierルールに準拠\r\n- **ドキュメント**: 新機能にはドキュメントを追加\r\n- **後方互換性**: 既存APIとの互換性を維持\r\n\r\n## 既知の課題・制限\r\n\r\n### APIレート制限\r\n- 1秒あたり最大10リクエスト\r\n- 1日あたり最大10,000リクエスト\r\n- 同時接続数最大5接続\r\n\r\n### データサイズ制限\r\n- 1回の取得可能データ: 最大1,000件\r\n- 列数制限: 最大300列\r\n- ※ 本ライブラリが自動分割処理でこれらの制限を透過的に解決\r\n\r\n### 対応ブラウザ\r\n- Chrome 80+\r\n- Firefox 75+  \r\n- Safari 13.1+\r\n- Edge 80+\r\n\r\n## 変更履歴\r\n\r\n### v0.9.0 (2026-06-07)\r\n- 初回リリース\r\n- 全API機能の型安全な実装\r\n- 自動リトライ・キャッシュ機能\r\n- GeoJSON対応\r\n- 座標→地域変換機能\r\n- ESM/CJS デュアル出力\r\n- 包括的テストスイート\r\n\r\n## ライセンス\r\n\r\nこのプロジェクトは [MIT License](./LICENSE) の下で公開されています。\r\n\r\n## 関連リンク\r\n\r\n- [47stats 公式サイト](https://www.47stats.com/)\r\n- [47stats APIリファレンス](https://api-stats.47stats.com/reference/v1/index.html)\r\n- [開発者チュートリアル ~ 47stats-apiの使い方](https://developers.47stats.com/)\r\n- [47maps ~ 統計データ地理情報システム](https://47maps.com)\r\n- [npm Package](https://www.npmjs.com/package/@47stats/api)\r\n- [GitHub Repository](https://github.com/47stats/47stats-api)\r\n- [Issue Tracker](https://github.com/47stats/47stats-api/issues)\r\n\r\n---\r\n\r\n> このライブラリは日本の47都道府県統計データを活用した  \r\n> 分析・可視化アプリケーションの開発を強力にサポートします。","readmeFilename":"README.md","_rev":"1-373f782a808de01d9ecbffa939e502ca"}