API ドキュメント

ゴミ収集カレンダーの日程データを、外部アプリケーションやウェブサイトから取得するための HTTP API です。レスポンスはすべて JSON で返ります。

基本情報・認証

認証

すべてのエンドポイントで API キーが必要です。以下のどちらかの方法で渡してください。

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://calendar.gomi53.com/api/v1/prefectures"

現在の収録状況

※ 全国を網羅したものではありません。収録済みのエリアは収録エリア一覧をご確認ください。

値の定義（曜日・週の数え方）

スケジュールを自前で解釈する場合、以下の3つの値の意味を正しく理解する必要があります。

day_of_week — 曜日

0 が日曜です（PHP の date('w') と同じ）。ISO 8601（月曜=1）とは異なります。

schedule_type — 収集の周期

week_calculation_type — 「第N週」の数え方

自治体によって「第2水曜」の定義が異なります。市区町村ごとに設定されており、 /data のレスポンスに含まれます。

エンドポイント

1. カレンダーデータの取得（推奨）

指定エリアの、指定月の収集日を日付展開済みで返します。 週の数え方や祝日振替はサーバー側で処理済みのため、クライアントで日付計算をする必要がありません。 通常はこのエンドポイントだけで足ります。

* id または（prefecture_name + city_name）のどちらかが必須です。

リクエスト例

curl -H "X-API-Key: YOUR_API_KEY" \\
     "https://calendar.gomi53.com/api/v1/data?id=11-13-186&year=2026&month=9"

レスポンス例（month 指定あり）

{
  "area": {
    "prefecture": { "id": 11, "name": "東京都" },
    "city":       { "id": 13, "name": "品川区" },
    "district":   { "id": 186, "name": "大井6丁目" }
  },
  "calendar": {
    "year": 2026,
    "month": 9,
    "week_calculation_type": "occurrence",
    "days": [
      {
        "date": "2026-09-01",
        "day": 1,
        "day_of_week": 2,
        "week_number": 1,
        "trash_types": [
          {
            "id": 1,
            "name": "可燃ごみ",
            "color": "#e53935",
            "icon": "",
            "district_id": 186,
            "district_name": "大井6丁目",
            "is_special": false,
            "note": null
          }
        ]
      }
    ]
  },
  "trash_types": [ ... ],
  "notes": "収集日の朝8時までに出してください",
  "last_updated": "2026-09-22 12:55:25"
}

レスポンス例（month 省略時 = 年度一括）

{
  "area": { ... },
  "calendar": {
    "fiscal_year": 2026,
    "months": [
      { "year": 2026, "month": 4,  "week_calculation_type": "occurrence", "days": [ ... ] },
      { "year": 2026, "month": 5,  ... },
      { "year": 2027, "month": 3,  ... }
    ]
  },
  ...
}

2. 都道府県一覧

階層をたどる起点です。パラメータは任意で、name を付けると名称の部分一致で絞り込めます。

curl -H "X-API-Key: YOUR_API_KEY" "https://calendar.gomi53.com/api/v1/prefectures"

[
  {
    "id": 11,
    "name": "東京都",
    "display_order": 0,
    "created_at": "...",
    "updated_at": "..."
  }
]

3. 市区町村一覧

curl -H "X-API-Key: YOUR_API_KEY" \\
     "https://calendar.gomi53.com/api/v1/cities?prefecture_id=11"

[
  {
    "id": 13,
    "prefecture_id": 11,
    "name": "品川区",
    "display_order": 0,
    "week_calculation_type": "occurrence",
    "created_at": "...",
    "updated_at": "..."
  }
]

4. 地区一覧

curl -H "X-API-Key: YOUR_API_KEY" \\
     "https://calendar.gomi53.com/api/v1/districts?city_id=13"

[
  { "id": 186, "city_id": 13, "name": "大井6丁目", "display_order": 0, ... }
]

5. 分別品目一覧

パラメータなしで全品目。prefecture_id / city_id / district_id を付けるとそのエリアで実際に使われている品目に絞り込みます。

curl -H "X-API-Key: YOUR_API_KEY" \\
     "https://calendar.gomi53.com/api/v1/trash_types"

[
  { "id": 1, "name": "可燃ごみ", "description": "", "color": "#e53935", "icon": "", ... }
]

color はカレンダー表示用のカラーコード、icon は Font Awesome のクラス名（未設定の場合は空文字）です。

6. 収集ルールの生データ（廃止）

エラーレスポンス

エラー時は HTTP ステータスコードと、error キーを含む JSON を返します。

{ "error": "Area not found" }

収録エリア一覧

prefecture_id / city_id はここでも確認できます （APIから取得する場合は /api/v1/prefectures と /api/v1/cities を使ってください）。

地区IDは /api/v1/districts?city_id={id} で取得してください。

利用上の注意

• データの正確性: 収集日程は各自治体の公表情報をもとに整備していますが、 変更が反映されるまでに時間差が生じる場合があります。 最終的な確認は各自治体の公式情報で行ってください。
• キャッシュ: 収集日程は頻繁には変わりません。クライアント側で1日程度のキャッシュを推奨します。 月あたりの呼び出しは1エリア1回で足ります。
• レート制限: 現在は明示的な制限を設けていませんが、常識的な範囲でご利用ください。 大量取得の予定がある場合は事前にご連絡ください。
• 互換性: パスに /v1 を含むエンドポイントは、破壊的変更を行う場合に /v2 を新設する方針です。既存フィールドの削除・意味変更は事前に告知します。

最終更新: 2026-09-22 ／ 本ページは ゴミカレンダー が提供しています。