{ "openapi": "3.1.1", "info": { "title": "MindCity AI Discovery Core API", "version": "0.1.0", "description": "MindCityの公開事業者情報を根拠と共に取得します。Read-only public entity discovery. Start with categories, search with structured filters, then fetch the returned ID. No authentication required for this pilot; 60 API requests/minute/source IP shared across these three operations. Null means unknown, not absent. Never infer hours, prices, availability or current operation. Sources describe record provenance, not a blanket redistribution license. Canonical pages use /profile/{id}/." }, "servers": [ { "url": "https://mindcity.org" } ], "externalDocs": { "url": "https://mindcity.org/developers", "description": "利用手順 / Developer guide" }, "paths": { "/api/v1/search": { "get": { "operationId": "searchEntities", "summary": "公開Entityを検索 / Search public entities", "security": [], "parameters": [ { "name": "q", "in": "query", "description": "名称・住所の部分一致。自然文を分解して地域/カテゴリを指定してください。Literal name/address substring, not semantic search.", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "category", "in": "query", "description": "categoriesが返すidの完全一致 / Exact category ID from listCategories", "required": false, "schema": { "type": "string", "maxLength": 128 } }, { "name": "region", "in": "query", "description": "都道府県等の保存値に完全一致。例: 神奈川県 / Exact stored region", "required": false, "schema": { "type": "string", "maxLength": 128 } }, { "name": "city", "in": "query", "description": "保存値に完全一致。区の表記差はqで補助 / Exact stored city; use q for wards when needed", "required": false, "schema": { "type": "string", "maxLength": 128 } }, { "name": "limit", "in": "query", "description": "返却件数 / Page size", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "description": "前回のnext_cursor。検索条件は維持してください / Reuse next_cursor with unchanged filters", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "成功 / Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "400": { "description": "条件不正 / Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "公開情報なし / Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "GETのみ / Method not allowed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "利用上限 / Rate limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "再試行までの秒数 / Seconds to retry", "schema": { "type": "integer" } } } }, "503": { "description": "一時障害 / Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "再試行までの秒数 / Seconds to retry", "schema": { "type": "integer" } } } } }, "description": "ID昇順のkeyset方式です。固定スナップショットではなく、更新時に結果が変化します。cursorは認証トークンではありません。全件数は返しません。Service matching is category-based; q does not search service descriptions. No open_now, inventory, bookings, job search, geo-distance or updated_since filters in v0.1. Unknown parameters and repeated parameters return 400." } }, "/api/v1/entities/{id}": { "get": { "operationId": "getEntity", "summary": "公式情報と根拠を取得 / Get public entity and sources", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "searchEntitiesが返したid / ID returned by searchEntities", "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" } } ], "responses": { "200": { "description": "成功 / Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "400": { "description": "条件不正 / Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "公開情報なし / Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "GETのみ / Method not allowed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "利用上限 / Rate limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "再試行までの秒数 / Seconds to retry", "schema": { "type": "integer" } } } }, "503": { "description": "一時障害 / Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "再試行までの秒数 / Seconds to retry", "schema": { "type": "integer" } } } } } } }, "/api/v1/categories": { "get": { "operationId": "listCategories", "summary": "公開カテゴリ一覧 / List public categories", "security": [], "parameters": [], "responses": { "200": { "description": "成功 / Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Categories" } } } }, "400": { "description": "条件不正 / Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "公開情報なし / Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "GETのみ / Method not allowed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "利用上限 / Rate limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "再試行までの秒数 / Seconds to retry", "schema": { "type": "integer" } } } }, "503": { "description": "一時障害 / Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "再試行までの秒数 / Seconds to retry", "schema": { "type": "integer" } } } } } } } }, "components": { "schemas": { "Category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, "DataQuality": { "type": "object", "properties": { "policy_version": { "const": "discovery-0.1" }, "status": { "const": "reviewed_record" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "legacy_timestamps": { "type": "object", "additionalProperties": { "type": "string" }, "description": "元DBの時差不明日時。Raw legacy DATETIME values; do not infer UTC/JST." }, "truncated_fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "policy_version", "status", "missing_fields", "warnings", "legacy_timestamps" ], "additionalProperties": false }, "EntitySummary": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "type": { "const": "entity", "description": "組織/拠点の区別は未正規化です。Entity granularity is not yet normalized." }, "name": { "type": "string" }, "category": { "$ref": "#/components/schemas/Category" }, "address": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] } }, "required": [ "text", "country", "region", "city" ], "additionalProperties": false }, "geo": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ], "additionalProperties": false } ], "description": "0,0と不正値はnull。住所との一致は未保証。Invalid/0,0 coordinates are null; not address-verified." }, "official_url": { "type": [ "string", "null" ], "format": "uri" }, "canonical_url": { "type": "string", "format": "uri" }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "時差が確定した日時のみ返します。Unknown timezone returns null; raw legacy values are in data_quality." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "時差が確定した日時のみ返します。Unknown timezone returns null; raw legacy values are in data_quality." }, "data_quality": { "$ref": "#/components/schemas/DataQuality" } }, "required": [ "id", "type", "name", "category", "address", "geo", "official_url", "canonical_url", "last_verified_at", "updated_at", "data_quality" ], "additionalProperties": false }, "Entity": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "type": { "const": "entity", "description": "組織/拠点の区別は未正規化です。Entity granularity is not yet normalized." }, "name": { "type": "string" }, "category": { "$ref": "#/components/schemas/Category" }, "address": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] } }, "required": [ "text", "country", "region", "city" ], "additionalProperties": false }, "geo": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ], "additionalProperties": false } ], "description": "0,0と不正値はnull。住所との一致は未保証。Invalid/0,0 coordinates are null; not address-verified." }, "official_url": { "type": [ "string", "null" ], "format": "uri" }, "canonical_url": { "type": "string", "format": "uri" }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "時差が確定した日時のみ返します。Unknown timezone returns null; raw legacy values are in data_quality." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "時差が確定した日時のみ返します。Unknown timezone returns null; raw legacy values are in data_quality." }, "data_quality": { "$ref": "#/components/schemas/DataQuality" }, "sources": { "type": "array", "maxItems": 21, "items": { "$ref": "#/components/schemas/Source" } }, "field_evidence": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "項目に関する過去の根拠への参照。現在値との完全一致を保証しません。Record evidence, not current-value attestation." } }, "required": [ "id", "type", "name", "category", "address", "geo", "official_url", "canonical_url", "last_verified_at", "updated_at", "data_quality", "sources", "field_evidence" ], "additionalProperties": false }, "Source": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "kind": { "type": "string" }, "retrieved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "時差が確定した日時のみ返します。Unknown timezone returns null; raw legacy values are in data_quality." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "時差が確定した日時のみ返します。Unknown timezone returns null; raw legacy values are in data_quality." }, "relationship": { "enum": [ "record_evidence", "official_destination", "reference_page" ] } }, "required": [ "id", "url", "kind", "retrieved_at", "verified_at", "relationship" ], "additionalProperties": false }, "SearchResult": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/EntitySummary" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "sort": { "const": "id_asc" } }, "required": [ "items", "limit", "has_more", "next_cursor", "sort" ], "additionalProperties": false }, "Categories": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "policy_version": { "const": "discovery-0.1" } }, "required": [ "items", "policy_version" ], "additionalProperties": false }, "Problem": { "type": "object", "properties": { "type": { "const": "about:blank" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "type", "status", "code", "detail" ], "additionalProperties": false } } } }