APIドキュメント｜たっきゅん

QUICK START

はじめに

ベースURL

https://www.ta9n.com/api/v1

形式

JSON / UTF-8

都道府県コード

JIS X 0401

参照APIは認証なしで利用できます。検索結果は data、ページ情報は meta に入ります。時刻はISO 8601形式です。

curl "https://www.ta9n.com/api/v1/places?prefecture=%E6%9D%B1%E4%BA%AC%E9%83%BD&keyword=%E5%8D%93%E7%90%83"

一覧レスポンス

{
  "data": [
    {
      "id": 30,
      "name": "中野区立総合体育館",
      "area": {"id": 13, "name": "東京都"},
      "city": "中野区",
      "status": {"key": "open", "label": "営業中"},
      "web_url": "https://www.ta9n.com/places/30"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 30,
    "total": 1,
    "generated_at": "2026-07-28T12:00:00+09:00"
  }
}

AUTHENTICATION

登録APIの認証

1. 会員登録・メール確認メール確認済みアカウントが必要です。
2. トークン発行プロフィール編集の「Wiki登録API」で発行します。
3. Bearer認証Authorizationヘッダーに指定します。

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
Accept: application/json

トークンは発行時に一度だけ表示されます。ソースコードへ直接書かず、環境変数などで管理してください。再発行すると以前のトークンは無効になります。

AREAS

都道府県コード

認証不要

GET https://www.ta9n.com/api/v1/areas

JIS X 0401に準拠した47都道府県のIDと名称を返します。東京都は13、埼玉県は11です。

PLACES

拠点API

JSONを開く →

GET https://www.ta9n.com/api/v1/places 拠点の検索・一覧

GET https://www.ta9n.com/api/v1/places/{id} 拠点の詳細

POST https://www.ta9n.com/api/v1/places 拠点を1件登録

POST https://www.ta9n.com/api/v1/places/bulk 拠点を最大100件まとめて登録

一覧の検索条件

項目	内容	例
prefecture	都道府県名。area_idよりこちらを推奨	東京都
area_id	JIS X 0401の都道府県コード	13
keyword	施設名・市区町村・住所の部分一致	中野区
status	open / temporarily_closed / closed	open
updated_since	この日時以降に更新された情報	2026-07-01T00:00:00+09:00
page	ページ番号	2
per_page	1〜100件（既定30件）	50

1件登録

name が必須です。都道府県は prefecture での名称指定を推奨します。area_id も同時指定した場合、不一致はエラーになります。

curl -X POST "https://www.ta9n.com/api/v1/places" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "たっきゅん卓球場",
    "prefecture": "東京都",
    "city": "港区",
    "address": "東京都港区赤坂4-2-3",
    "official_url": "https://example.com/",
    "status": "open",
    "table_count": 8,
    "opening_hours": "9:00〜21:00",
    "usage_fee_note": "1時間 1,000円",
    "amenities": ["racket_rental", "changing_room", "shower"],
    "equipment_note": "卓球マシンあり"
  }'

登録できる項目と値

name必須・120文字以内

prefecture / area_id都道府県名 / JISコード

city / address市区町村 / 住所

map_url / official_urlhttp・https URL

note補足・2,000文字以内

status / status_note営業状態 / 状態の補足

table_count卓球台数・1〜999

opening_hours営業時間・休館日

usage_fee_note利用料金の補足

amenities設備キーの配列

equipment_note設備詳細・1,000文字以内

STATUS

open / temporarily_closed / closed

AMENITIES

racket_rental / balls / changing_room / shower / locker / air_conditioning / parking / accessible / shop / spectator_seats

一括登録

places 配列へ最大100件指定します。全行を検証してから登録するため、不正な行がある場合は一件も書き込みません。公式URL・名称と地域・住所から重複を判定し、登録済みの行は existing で返します。

{
  "places": [
    {"name": "A体育館", "prefecture": "東京都", "city": "港区"},
    {"name": "B卓球場", "prefecture": "埼玉県", "city": "草加市"}
  ]
}

EVENTS

イベントAPI

JSONを開く →

GET https://www.ta9n.com/api/v1/events 今後のイベント一覧

GET https://www.ta9n.com/api/v1/events/{id} イベントの詳細

POST https://www.ta9n.com/api/v1/events イベントを1件登録

一覧の検索条件

area_id（JISコード） category status updated_since include_past=1 page per_page（最大100）

イベント登録

curl -X POST "https://www.ta9n.com/api/v1/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "たっきゅんオープン卓球大会",
    "category": "tournament",
    "starts_at": "2026-09-20 09:00",
    "ends_at": "2026-09-20 17:00",
    "area_id": 13,
    "venue_name": "たっきゅん卓球場",
    "organizer_name": "たっきゅん実行委員会",
    "official_url": "https://example.com/event",
    "participation_fee": 1500,
    "level": "オープン",
    "description": "観戦のみでも参加できます。",
    "status": "scheduled"
  }'

必須項目

title / category / starts_at / status

place_id を指定すると、地域を拠点から自動補完できます。

任意項目

ends_at / place_id / area_id / venue_name / organizer_name / official_url / participation_fee / level / description

category： tournament（大会） / clinic（講習会） / watching（観戦） / exchange（交流会） / festival（卓球イベント） / other（その他）
status： scheduled（開催予定） / postponed（延期） / cancelled（中止） / finished（終了）

RESPONSES & LIMITS

レスポンス・エラー・制限

HTTP	意味	主なケース
200	成功	参照成功・一括登録がすべて登録済み
201	作成成功	新しい情報を登録
401	認証エラー	トークンなし・無効
403	権限エラー	メール確認が未完了
404	未検出	IDが存在しない・非公開
409	重複	同じ拠点またはイベントが登録済み
422	入力エラー	必須項目・形式・列挙値が不正
429	回数制限	短時間にリクエストが集中

レート制限

参照APIは120回/分、1件登録は30回/分、拠点の一括登録は10回/分です。

Wiki貢献ポイント

新規登録は通常+10pt。Wiki報酬は合計1日30ptまでで、付与数は meta.wiki_points_awarded に入ります。

入力エラーの例

{
  "message": "都道府県名と都道府県コードが一致しません。",
  "errors": {
    "area_id": ["都道府県名と都道府県コードが一致しません。"]
  }
}