はじめに

個人で運営している中古バイク横断検索サービス「MotoHub」で、中古バイク市場のデータを外部提供するAPIを4本公開しました。

この記事は、**「すでに画面で動いている集計ロジックを、壊さずにAPI化する」**という、地味だけど個人開発でよくある作業の設計と、その過程でハマった罠をまとめたものです。同じことをやる人の参考になれば。

スタック：Laravel 12 / PHP 8.3 / MySQL / Redis / Meilisearch

公開した4本：

エンドポイント	内容
`GET /api/v1/rankings/listings`	排気量クラス別の流通台数ランキング
`GET /api/v1/rankings/price-trends`	相場推移（値下がり/高騰）ランキング
`GET /api/v1/models/{id}/stats`	車種別の市場データ（地域/年式/走行距離/価格帯）
`GET /api/v1/market/stats`	市場全体のトレンド（地域/年式/走行距離）

ドキュメントは /data に置いています。

設計の方針：「画面のロジックを正にして、APIはそれを包むだけ」

4本のうち3本は、すでにWebページでユーザーにグラフやランキングをUI表示していたものでした。つまり集計ロジックは既に存在している。ここで取れる選択は2つ：

APIのために集計を書き直す
既存の集計を唯一の正として、APIはそれを呼んで整形するだけにする

迷わず2です。理由は単純で、1にすると「画面の数字」と「APIの数字」が二重管理になり、いつか必ずズレるから。「MotoHub調べ」として外部に出すデータが、サイトを見た数字と違ったら信用を失います。

具体的には、コントローラに private で埋まっていた集計メソッドを Service クラスに抽出し、ページもAPIも同じServiceを呼ぶ形にしました。

// Before: コントローラ内に集計が埋まっている
class RankingController {
    private function getModelStats(int $id): array { /* 重い集計 */ }
}

// After: Service に抽出。ページもAPIも同じものを呼ぶ
class ModelStatsService {
    public function getStats(int $id): array {
        return Cache::remember("model_stats_ranking_v6_{$id}", 604800, fn () => $this->compute($id));
    }
    private function compute(int $id): array { /* 移動しただけ・ロジックは不変 */ }
}

ポイントは、抽出時にロジックを一行も変えないこと。キャッシュキーもTTLもそのまま移植する。こうすると「既存ページの挙動は完全に同一」を保証でき、APIは安全に相乗りできます。リファクタの差分が +342 / −117 で、117行の削除が「コントローラからの移動」だけ、という状態が理想です。

ハマった罠①：PHPは連想配列の「数値文字列キー」を勝手にintにする

排気量クラスを、こう定数で持っていました。

public const RANGES = [
    '125'   => [101, 125],
    '250'   => [226, 250],
    '400'   => [348, 400],
    'large' => [751, null],
];

クラス一覧をループしてランキングを作る処理で、最初こうしていました。

foreach (self::RANGES as $class => $range) {
    $this->classRanking($class, ...); // classRanking(string $class)
}

これが本番で TypeError: Argument #1 ($class) must be of type string, int given で落ちました。

原因は、PHPが連想配列の「整数として解釈できる文字列キー」を自動的に int に正規化する仕様です。'125' は 125(int) になり、'large' だけ string のまま。つまり large は通り、125/250/400 で型エラー。

教訓：キーに意味を持たせた配列をループするとき、数値っぽいキーは int 化される。 修正は「キーでなく値の配列でループ」。

foreach (['125', '250', '400', 'large'] as $class) { // string のまま保持
    $this->classRanking($class, ...);
}

classRanking(string $class) の型宣言を緩める誘惑に駆られますが、それは間違い。large という非数値キーがある以上、呼び出し側で string を保証するのが正解です。

ハマった罠②：「クラスの境界」は実データを見ないと決められない

「250ccクラス」を素直に 126〜250cc で集計すると、150/155/160ccのスクーターが混ざります。"250ccバイク"として見せたいのは実質 226〜250cc。

さらに6区分に拡張したとき、各帯の下限で実車種の分布を確認する必要がありました。たとえば「400ccクラス」の下限を 376 にするか 348 にするかで、GB350（348cc）が入るかどうかが変わる。キリのいい数字（350, 400…）で機械的に切ると、入れたい車種が落ちたり、意図しない車種が混ざったりします。

教訓：ドメイン特有の「区切り」は、定数の見た目の綺麗さではなく、実データの分布で決める。 そして公開後は、各クラスの上位数件を必ず目視して、変な車種が混ざっていないか確認する。

ハマった罠③：「車種ごとなら平気」な集計が、市場全体にすると牙をむく

4本目の「市場全体トレンド」で、年式別ランキングを作ったら、model_year = 5010 という明らかなゴミデータが1位に来ました。

面白いのは、同じ集計ロジックを車種別ページでは何ヶ月も使っていたのに、表面化していなかったこと。車種別は「1車種に絞り込み＋上位10件」なので、ゴミ年式が紛れていても上位に出てこなかった。市場全体に広げて初めて、データ品質の穴が見えたわけです。

対策は健全な年式範囲（1900〜当年+1）で絞る。車種別の挙動は変えず、市場全体クエリにだけ制約を足すことで、既存を壊さず修正しました。

教訓：スコープを広げると、今まで隠れていたデータ品質の問題が顕在化する。 「車種ごとで動いてたから市場全体でも大丈夫」は成り立たない。

おまけ：公開APIにした瞬間、パフォーマンスが「自分の問題」でなくなる

市場全体の年式・走行距離集計は、cappedSold（成約判定のためのウィンドウ関数 ROW_NUMBER()）が約14万行を舐めるため、コールドで約8秒かかりました。

画面なら1時間キャッシュで隠せます（ウォーム時2ms）。でも外部公開APIは、知らない人がキャッシュの切れた瞬間に叩く。そのリクエストは8秒待たされるし、同時に来ればDBに負荷が乗る。「自分しか踏まないキャッシュミス」と「他人が踏むキャッシュミス」は重みが違う。

当座は1時間キャッシュで凌ぎつつ、スケジューラでの定期ウォーム、あるいは日次の事前集計テーブルを検討中です。whereIn で capped ID を持ち回る案も考えましたが、対象が約10万行で placeholder 上限を超えるため不採用。このあたりは続編で書くかもしれません。

教訓：公開APIにする＝パフォーマンスがUXではなくインフラの問題になる。 キャッシュは「隠す」だけで「速くする」わけではないので、重いクエリは結局どこかで根本対処が要る。

まとめ

既存の集計をServiceに抽出して唯一の正にし、ページもAPIも同じものを呼ぶ。これで数字のズレと二重管理を防ぐ
抽出時はロジックを変えない。差分が「移動だけ」になっている状態を目指す
PHPの数値文字列キーの int 化、ドメインの境界定義、スコープ拡大によるデータ品質の顕在化 ―― この3つは個人開発でも普通に踏む
公開APIにするとパフォーマンスの意味が変わる。キャッシュは万能ではない

データAPIは /data で公開しています。中古バイクのデータを使ってみたい方はどうぞ。