developer docs

Search API

自治体オープンデータなどの公開データと、マワリミチの公開投稿を、出典・ライセンス表示を保ったまま検索できる公開 API です。認証は不要で、地域（市区町村）を指定して施設・イベント・記事を検索できます。

エンドポイント

GET

/api/v1/search?region=<region>

指定した地域の施設・イベント・記事を 1 つの結果セットで返します。外部の公開データには、出典・ライセンスの情報が付きます。

ベース URL: https://api.mawarimichi.app

パラメータ

名前	説明
`region`必須	地域。1〜5 件、カンマ区切り。例: city-28213 または city-28213,city-28214
`kind`	種類。all / facility / event / article（省略時は all）
`q`	検索キーワード
`origin`	情報元。all / native（マワリミチの公開投稿）/ external（外部の公開データ）
`tag_all`	すべてに一致するタグ（カンマ区切り）
`tag_any`	いずれかに一致するタグ（カンマ区切り）
`limit`	1 回に返す件数
`cursor`	続きを取得する位置。直前のレスポンスの next_cursor をそのまま渡します
`from / to_exclusive`	イベント検索（kind=event）専用の期間。RFC 3339 形式。例: 2026-11-02T00:00:00+09:00

使用例

# 認証なしで検索（地域 city-28213 の施設から「小学校」を探す）
curl 'https://api.mawarimichi.app/api/v1/search?region=city-28213&kind=facility&q=小学校'

# Response (例・値は説明用の架空のものです)
{
  "items": [
    {
      "id": "sample-0001",
      "origin": "external",
      "kind": "facility",
      "title": "サンプル市立サンプル小学校",
      "address": "サンプル県サンプル市サンプル町1-2-3",
      "lat": 35.0,
      "lng": 135.0,
      "display_url": "https://example.com/facilities/sample-0001",
      "source": {
        "source_name": "サンプル市オープンデータ",
        "license_type": "CC-BY-4.0",
        "license_url": "https://example.com/license",
        "attribution_text": "出典: サンプル市オープンデータ"
      }
    }
  ],
  "next_cursor": "sample-cursor-token",
  "result_state": "ready",
  "search_mode": "lexical"
}

続きがあるときは next_cursor が返ります。次のリクエストの cursor にそのまま渡してください。

認証・制限・ステータス

認証: 不要（匿名）
レート制限: 30 リクエスト / 分 / IP。超えると 429 と Retry-After を返します
ブラウザからの呼び出し（CORS）は https://mawarimichi.app のみ許可しています。サーバー側からの呼び出しは CORS の影響を受けません

400指定した値が不正です（region が無い・多すぎるなど）
409refresh_required。検索条件の状態が更新されています。cursor を付けずに最初から検索し直してください
429リクエストが多すぎます。Retry-After ヘッダーに従って、時間をおいてから再試行してください
503一時的に利用できません。時間をおいて再試行してください

MCP 経由 (Claude Desktop / Cursor / ChatGPT) の利用は /docs/mcp へ。有料プランの詳細は料金プランをご覧ください。

返却するデータと出典表示

返すのは、提供元が API での再配布を認めている公開データと、マワリミチの公開投稿です。

外部の公開データの各件には、source.source_name / source.license_type / source.license_url / source.attribution_text が付きます。結果を表示するときは、出典表示（attribution_text）を必ず表示してください。

お問い合わせは /contact から。料金プランは /pricing。