Merukari Python メルカリリサーチ運用

API連携

最初の1本から迷わない API ガイド。

外部システムからデータを読むために必要な URL、認証方法、サンプルコード、レスポンス例を一つにまとめています。

最初の流れを見る 先に使い方を見る
まず覚えること
  • 外部連携は /v1/{taskNo} から始めるのが最短です。
  • 認証は API key を使う方法がいちばん簡単です。
  • 返却順は既定で最新順です。

最初の流れ

最初にやる3ステップ

01

Task No を確認する

ホームの「登録タスク」に表示されている番号を確認します。API ではこの番号を使います。

02

認証方法を決める

外部システムから読むだけなら API key、管理画面の自動操作が必要なら Cookie と CSRF を使います。

03

curl で一度試す

まず curl で成功させてから、JavaScript や Python に移すと確認が早くなります。

認証

認証方法の選び方

おすすめ

X-API-Key

外部システム連携ならこれが最も簡単です。ヘッダーに API key を付けるだけで読み出せます。

代替

Authorization: Bearer

API key を Bearer トークンとして送る方法です。既存クライアントに乗せやすいときはこちらでも使えます。

安全運用

URLには載せない

API key はブラウザ履歴やアクセスログに残りやすいため、クエリ文字列では受け付けません。

内部API

Cookie + CSRF

/api/* を使うときの方式です。ログインで Cookie を取得し、更新系では X-CSRF-Token を付けます。

API一覧

まず覚えるエンドポイント

Method Path 認証 用途
GET /health 不要 サーバーが応答しているか確認します。
GET /v1/{taskNo} API key または Cookie 取得済み商品を最新順で返します。
GET /s/{shortCode} 不要 短縮URLから商品リンクへ移動します。
POST /api/auth/login 不要 内部 API 用のログインです。
GET /api/me Cookie 現在のログイン状態とワークスペース情報を確認します。
GET /api/status Cookie 件数サマリーや設定の一部を返します。
POST /api/tasks/{taskNo}/run Cookie + CSRF 対象タスクを手動実行します。

基本ルール

/v1/{taskNo} の見方

taskNo

ホームの登録タスクに表示される番号です。存在しない場合や権限外の場合は 404 になります。

limit

返却件数です。例: limit=100。全件取得したいときは limit=all を使えます。

offset

ページ送り開始位置です。大量データを分けて取得したいときに使います。

並び順

返却順は既定で最新順です。新しい取得結果から返ります。

重複保存

同一タスクで同じ商品を再取得しても、重複レコードを増やさず更新扱いにします。

共通ワークスペース

すべてのログインユーザーと API key は同じ既定ワークスペースのデータを参照します。

サンプル

そのまま試せるコード

curl

外部 API を読む

curl -s \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://s.by0.uk/v1/1?limit=3"

JavaScript

fetch で読む

const response = await fetch("https://s.by0.uk/v1/1?limit=3", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await response.json();
console.log(data.records);

Python

requests で読む

import requests

url = "https://s.by0.uk/v1/1"
params = {"limit": 3}
headers = {"X-API-Key": "YOUR_API_KEY"}

response = requests.get(url, params=params, headers=headers, timeout=30)
response.raise_for_status()

data = response.json()
for row in data["records"]:
    print(row["title"], row["price"])

Python

ログインして手動実行する

import requests

base_url = "https://s.by0.uk"
session = requests.Session()

login_response = session.post(
    f"{base_url}/api/auth/login",
    json={
        "username": "YOUR_USERNAME",
        "password": "YOUR_PASSWORD",
    },
    timeout=30,
)
login_response.raise_for_status()

csrf_token = login_response.json()["me"]["csrf_token"]

run_response = session.post(
    f"{base_url}/api/tasks/1/run",
    json={},
    headers={"X-CSRF-Token": csrf_token},
    timeout=120,
)
run_response.raise_for_status()

print(run_response.json())

レスポンス例

返却される JSON の例

GET /health

ヘルスチェック

{
  "status": "ok",
  "time": "2026-04-01T11:00:00+09:00"
}

GET /v1/1?limit=2

外部公開 API

{
  "task": {
    "task_no": 1,
    "task_name": "ポケカ",
    "keyword": "ポケカ",
    "category": "トレーディングカード",
    "source": "mercari"
  },
  "total": 120,
  "offset": 0,
  "count": 2,
  "records": [
    {
      "task_no": 1,
      "title": "ポケモンカード まとめ売り SR入り",
      "image_url": "https://static.mercdn.net/item/detail/orig/photos/m12345678901_1.jpg",
      "product_url": "https://jp.mercari.com/item/m12345678901",
      "price": 6800,
      "short_url": "https://s.by0.uk/s/Ab12Cd34",
      "fetched_at": "2026-04-01T08:49:18+09:00"
    }
  ]
}

POST /api/auth/login

ログイン成功

{
  "message": "ログインしました。",
  "me": {
    "authenticated": true,
    "auth_type": "session",
    "username": "owner",
    "tenant_id": 1,
    "tenant_name": "Default",
    "tenant_slug": "default",
    "is_superadmin": false,
    "csrf_token": "CSRF_TOKEN_HERE"
  }
}

GET /api/status

状態確認

{
  "server_time": "2026-04-01T11:00:00+09:00",
  "base_url": "https://s.by0.uk",
  "counts": {
    "task_count": 1,
    "enabled_task_count": 1,
    "item_count": 120
  },
  "tasks_due_now": [1]
}