get_stats_list
Search and retrieve statistical table information from Japan's official government statistics portal (e-Stat) using keywords, survey years, statistical codes, and other filters to find relevant data sets.
Instructions
統計表情報を検索する.
Args: search_word: 検索キーワード（統計表名、調査名など） survey_years: 調査年（YYYY形式、範囲指定はYYYY-YYYY） stats_field: 統計分野コード（2桁） stats_code: 政府統計コード（5桁または8桁） gov_code: 政府機関コード open_years: 公開年（YYYY形式、範囲指定はYYYY-YYYY） stats_name_list: 調査・集計の種類 start_position: データ取得開始位置 updated_date: 更新日（YYYY-MM-DD） limit: 取得件数（デフォルト10件、最大100件）
Returns: 統計表情報のリスト
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| search_word | No | ||
| survey_years | No | ||
| stats_field | No | ||
| stats_code | No | ||
| gov_code | No | ||
| open_years | No | ||
| stats_name_list | No | ||
| start_position | No | ||
| updated_date | No | ||
| limit | No |
Input Schema (JSON Schema)
{
"properties": {
"gov_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"limit": {
"default": 10,
"type": "integer"
},
"open_years": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"search_word": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"start_position": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"stats_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"stats_field": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"stats_name_list": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"survey_years": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"updated_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
}
Implementation Reference
- e_stats_mcp/tools/stats.py:68-111 (handler)The core handler function implementing the logic for the 'get_stats_list' tool. It constructs parameters and makes an API request to e-Stat's getStatsList endpoint to retrieve statistics list.async def get_stats_list( search_word: str | None = None, survey_years: str | None = None, stats_field: str | None = None, stats_code: str | None = None, gov_code: str | None = None, open_years: str | None = None, stats_name_list: str | None = None, start_position: int | None = None, updated_date: str | None = None, limit: int = 10, ) -> dict: """統計表情報を検索する. Args: search_word: 検索キーワード（統計表名、調査名など） survey_years: 調査年（YYYY形式、範囲指定はYYYY-YYYY） stats_field: 統計分野コード（2桁） stats_code: 政府統計コード（5桁または8桁） gov_code: 政府機関コード open_years: 公開年（YYYY形式、範囲指定はYYYY-YYYY） stats_name_list: 調査・集計の種類 start_position: データ取得開始位置 updated_date: 更新日（YYYY-MM-DD） limit: 取得件数（デフォルト10件、最大100件） Returns: 統計表情報のリスト """ params = _build_stats_list_params( search_word=search_word, survey_years=survey_years, stats_field=stats_field, stats_code=stats_code, gov_code=gov_code, open_years=open_years, stats_name_list=stats_name_list, start_position=start_position, updated_date=updated_date, limit=limit, ) response = await _make_request("json/getStatsList", params) return cast(dict[str, Any], response)
- e_stats_mcp/main.py:44-44 (registration)Registration of the 'get_stats_list' tool using the FastMCP decorator mcp.tool().mcp.tool()(get_stats_list)
- e_stats_mcp/tools/stats.py:114-152 (helper)Helper function to assemble common parameters for the getStatsList API calls, used directly by the handler.def _build_stats_list_params( *, search_word: str | None = None, survey_years: str | None = None, stats_field: str | None = None, stats_code: str | None = None, gov_code: str | None = None, open_years: str | None = None, stats_name_list: str | None = None, start_position: int | None = None, updated_date: str | None = None, limit: int = 10, ) -> dict: """getStatsList系の共通パラメータを組み立てる.""" params = { "lang": "J", "limit": str(min(limit, 100)), } if search_word: params["searchWord"] = search_word if survey_years: params["surveyYears"] = survey_years if stats_field: params["statsField"] = stats_field if stats_code: params["statsCode"] = stats_code if gov_code: params["governmentCode"] = gov_code if open_years: params["openYears"] = open_years if stats_name_list: params["statsNameList"] = stats_name_list if start_position: params["startPosition"] = str(start_position) if updated_date: params["updatedDate"] = updated_date return params
- e_stats_mcp/tools/stats.py:17-66 (helper)Core utility function to perform HTTP requests to the e-Stat API, called by the handler to fetch data from 'json/getStatsList' endpoint.async def _make_request( endpoint: str, params: dict | None = None, *, method: str = "GET", format: str = "json", data: dict | None = None, ) -> dict[str, Any] | str: """e-Stat APIへのリクエストを実行する. Args: endpoint: APIエンドポイント（例: \"json/getStatsList\"） params: クエリパラメータ method: HTTPメソッド（GET/POST） format: レスポンス形式（\"json\" または \"csv\"） data: POST時のフォームデータ Returns: JSONの場合はdict、CSVの場合は文字列 Raises: ValueError: APIキーが設定されていない場合 httpx.HTTPError: API通信エラー """ settings = get_settings() if not settings.E_STAT_APP_ID: raise ValueError( "E_STAT_APP_ID環境変数が設定されていません。" "https://www.e-stat.go.jp/api/ からアプリケーションIDを取得してください。" ) url = f"{E_STAT_API_BASE}/{endpoint}" request_params = {"appId": settings.E_STAT_APP_ID, **(params or {})} http_method = method.upper() async with httpx.AsyncClient() as client: if http_method == "POST": response = await client.post( url, params=request_params, data=data, timeout=DEFAULT_TIMEOUT ) else: response = await client.get( url, params=request_params, timeout=DEFAULT_TIMEOUT ) response.raise_for_status() if format == "csv": return response.text return response.json()