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

QUICK START

はじめに

ベースURL

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

形式

JSON / UTF-8

都道府県コード

JIS X 0401

場所・イベント・フォーラムの参照APIは認証なしで利用できます。自分のレーティングAPIはBearer認証が必要です。検索結果は 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": "営業中"},
      "cover_photo_url": "https://example.com/place-photo.jpg",
      "photos_count": 3,
      "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. トークン発行プロフィール編集の「たっきゅんAPI」で発行します。
3. Bearer認証Authorizationヘッダーに指定します。

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

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

権限（スコープ）

wiki:write

場所・イベントWikiの登録

ratings:read

自分のレーティング参照

ratings:write

自分のレーティング登録・更新

必要な権限だけをプロフィール編集で有効にできます。既存のWiki用トークンには、レーティングの読み書き権限は自動追加されません。

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件まとめて登録

GET APIが返すのは「一般公開」のイベントだけです。フォロワー限定・メンバー限定のサークルイベントは、Web画面で閲覧権限を確認して表示します。

一覧の検索条件

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

1件登録

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

登録済み写真の代表URLと枚数は cover_photo_url・photos_count で取得できます。写真の投稿は、著作権と現地の撮影ルールを確認できるよう、現在は場所ページからのみ受け付けます。

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,
    "ball_type": "both",
    "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

ball_typestandard（硬式）/ large（ラージ）/ both（両方）

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",
    "application_method": "公式サイトの申込フォームから",
    "application_url": "https://example.com/event/entry",
    "application_deadline": "2026-09-10 23:59",
    "participation_fee": 1500,
    "level": "オープン",
    "description": "観戦のみでも参加できます。",
    "status": "scheduled"
  }'

必須項目

title / category / starts_at / status

place_id を指定すると、地域を場所情報から自動補完できます。

任意項目

ends_at / place_id / circle_id / visibility / area_id / venue_name / organizer_name / official_url / application_method / application_url / application_deadline / participation_fee / level / description

visibility は public / followers / members。限定公開は、操作権限のある circle_id と一緒に指定します。

application_deadline はイベント開始日時以前を指定してください。GETレスポンスでは期限判定済みの application_closed も返します。

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

PERSONAL RATINGS

レーティングAPI

本人の記録のみ

P4matchなどで記録している自分のレート推移を、外部ツールから参照・登録できます。非公開のシリーズも本人のトークンでは取得できますが、他の会員の履歴にはアクセスできません。

GET

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

ratings:read

自分のレーティング一覧

POST

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

ratings:write

レーティングを作成

PATCH

https://www.ta9n.com/api/v1/ratings/{series_id}

ratings:write

名前・色・公開設定を更新

GET

https://www.ta9n.com/api/v1/ratings/{series_id}/entries

ratings:read

履歴を30件ずつ取得

POST

https://www.ta9n.com/api/v1/ratings/{series_id}/entries

ratings:write

履歴を1件登録

POST

https://www.ta9n.com/api/v1/ratings/{series_id}/entries/bulk

ratings:write

履歴を最大100件まとめて登録

シリーズを作成

curl -X POST "https://www.ta9n.com/api/v1/ratings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "P4matchレート",
    "color": "#d1713f",
    "is_public": true
  }'

履歴をまとめて登録

entries 配列へ最大100件を指定します。全行を検証してから保存するため、1行でも不正な場合は1件も登録しません。シリーズ全体では最大500件です。

curl -X POST "https://www.ta9n.com/api/v1/ratings/{series_id}/entries/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "recorded_on": "2026-07-20",
        "value": 1532,
        "event_name": "夏季レーティング大会",
        "source_url": "https://example.com/results/1532",
        "note": "予選リーグ",
        "client_reference": "p4match-result-12345"
      },
      {
        "recorded_on": "2026-07-27",
        "value": 1558,
        "event_name": "週例会",
        "client_reference": "p4match-result-12410"
      }
    ]
  }'

履歴の項目

recorded_on / value / event_name / source_url / note / client_reference

recorded_on と value が必須です。

重複を防ぐ識別ID

client_reference には外部サービス側の一意な結果IDを指定してください。同じID・同じ内容の再送は existing となり、件数は増えません。同じIDで内容が異なる場合は409です。

API登録の出典はサーバー側で「外部取込・未確認」に固定されます。確認済みへの変更や投稿者の指定はできず、Wiki貢献ポイントの対象外です。

履歴の検索条件

from（開始日） to（終了日） updated_since order=asc|desc page per_page（最大100・既定30）

FORUM

フォーラムAPI

JSONを開く →

公開中の話題と返信を読み取り専用で取得できます。場所・イベント・サークルと関連する会話を、地域サイトや施設案内へ掲載できます。

GET https://www.ta9n.com/api/v1/forum/threads 話題の検索・一覧

GET https://www.ta9n.com/api/v1/forum/threads/{id} 話題と返信の詳細

一覧の検索条件

q channel purpose place_id community_event_id circle_id unanswered=1 posted_since page per_page（最大100）

curl "https://www.ta9n.com/api/v1/forum/threads?channel=local&unanswered=1"

サイトへの埋め込み

外部サイトには、投稿機能を持たない読み取り専用のウィジェットを設置できます。channel、area_id、limit（最大20件）で内容を絞れます。

<iframe src="https://www.ta9n.com/embed/forum?channel=local&area_id=13&limit=5" title="たっきゅん 卓球フォーラム" loading="lazy" sandbox="allow-popups allow-popups-to-escape-sandbox" style="width:100%;height:420px;border:0"></iframe>

RESPONSES & LIMITS

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

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

レート制限

参照APIは120回/分、1件登録は30回/分、一括登録は10回/分です。レーティング一括登録は1回最大100件です。

Wiki貢献ポイント

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

入力エラーの例

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