米国の大都市のほとんどは、同一のSocrata Open Data APIを通じてレストラン検査を公開しています。その統一性こそが落とし穴です。トランスポートは同一ですが、カラム名、スコアの極性、行の粒度、更新周期は異なります。このガイドでは、7つの自治体のデータセットと、2026-07-20に各データセットを実際にライブクエリした際に遭遇した具体的な失敗モードを列挙します。

以下の数値、カラム名、データセットIDはすべて、その日にライブエンドポイントに対して実際に実行したリクエストから取得したものです。確認できなかった点については、推測ではなく「確認できなかった」と明記しています。

7つのデータセット

7つすべてが、認証なしのリクエストに対してHTTP 200を返しました。日付カラムは範囲フィルタに必要となるものであり、7つのうち3つで異なります。

都市または郡 ドメイン データセットID 日付カラム 公式データセットタイトル
New York, NY data.cityofnewyork.us 43nn-pn8j inspection_date DOHMH New York City Restaurant Inspection Results
Chicago, IL data.cityofchicago.org 4ijn-s7e5 inspection_date Food Inspections
Cincinnati, OH data.cincinnati-oh.gov rg6p-b3h3 action_date Cincinnati Food Safety Program
Austin, TX datahub.austintexas.gov ecmv-9xxi inspection_date Food Establishment Inspection Scores
King County, WA data.kingcounty.gov f29f-zza5 inspection_date Food Establishment Inspection Data
Boulder County, CO data.colorado.gov 6ytb-f2cq rec_date Restaurant Inspections in Boulder County (2025-present)
Montgomery County, MD data.montgomerycountymd.gov dkrp-gr48 inspection_start_date HHS - Food Inspection Data from July 2024 and onward

都市を信頼する前に鮮度を確認する

「オープンデータポータル」＝「最新」とは限りません。データセットの実際の状況を教えてくれる安価なシグナルが2つあります。日付カラムに対するmax()と、すべてのポータルが返すX-SODA2-Truth-Last-Modifiedレスポンスヘッダです。都市を基盤に何かを構築する前に、必ず実行してください。

const DATASETS = [
  { city: 'New York, NY',        domain: 'data.cityofnewyork.us',       id: '43nn-pn8j', date: 'inspection_date' },
  { city: 'Chicago, IL',         domain: 'data.cityofchicago.org',      id: '4ijn-s7e5', date: 'inspection_date' },
  { city: 'Cincinnati, OH',      domain: 'data.cincinnati-oh.gov',      id: 'rg6p-b3h3', date: 'action_date' },
  { city: 'Austin, TX',          domain: 'datahub.austintexas.gov',     id: 'ecmv-9xxi', date: 'inspection_date' },
  { city: 'King County, WA',     domain: 'data.kingcounty.gov',         id: 'f29f-zza5', date: 'inspection_date' },
  { city: 'Boulder County, CO',  domain: 'data.colorado.gov',           id: '6ytb-f2cq', date: 'rec_date' },
  { city: 'Montgomery Cnty, MD', domain: 'data.montgomerycountymd.gov', id: 'dkrp-gr48', date: 'inspection_start_date' },
];

const DAY = 86400000;

for (const d of DATASETS) {
  const url = `https://${d.domain}/resource/${d.id}.json`
    + `?$select=max(${d.date}) AS newest&$where=${d.date} IS NOT NULL`;
  const res = await fetch(url, { headers: { Accept: 'application/json' } });
  if (!res.ok) {
    console.log(`${d.city.padEnd(22)} HTTP ${res.status}`);
    continue;
  }
  const newest = (await res.json())[0]?.newest ?? null;
  const lag = newest ? Math.round((Date.now() - Date.parse(newest)) / DAY) : null;
  const modified = res.headers.get('x-soda2-truth-last-modified');
  console.log(
    `${d.city.padEnd(22)} newest=${(newest ?? 'none').slice(0, 10)}` +
    `  lag=${lag === null ? '?' : lag + 'd'}  portal_modified=${modified ?? 'n/a'}`
  );
}

Enter fullscreen mode Exit fullscreen mode

fresh.mjsとして保存し、Node 18以降でnode fresh.mjsを実行してください。2026-07-20に得られた出力は以下のとおりです。

都市 最新検査日 遅延 ポータル最終更新
New York, NY 2026-07-19 2 days Mon, 20 Jul 2026 22:09 GMT
Chicago, IL 2026-07-16 5 days Sun, 19 Jul 2026 09:09 GMT
Cincinnati, OH 2026-07-29 -8 days Mon, 20 Jul 2026 02:57 GMT
Austin, TX 2026-05-22 60 days Mon, 15 Jun 2026 17:01 GMT
King County, WA 2025-11-26 237 days Thu, 04 Dec 2025 22:36 GMT
Boulder County, CO 2026-02-26 144 days Thu, 23 Apr 2026 01:28 GMT
Montgomery County, MD 2026-07-17 4 days Mon, 20 Jul 2026 04:31 GMT

この結果から3つのことがわかります。New York、Chicago、Montgomery Countyは実質的に最新です。King Countyは2025-11-26より新しい検査を公開しておらず、ポータル自体も2025-12-04以降更新されていなかったため、それに基づく消費者向け「現在の衛生グレード」は8か月も古いデータに基づくことになります。Cincinnatiは未来の日付である2026-07-29の行を1件含んでいたため、負の遅延が返されました。max(date)を今日の上限とみなしてはいけません。

このチェックは定期的に再実行してください。先四半期には最新だったポータルが、気づかないうちに更新を停止している可能性があります。

落とし穴1：DESCソートでNULLが先頭に来る

最新順にページングする明らかな方法は$order=inspection_date DESCです。Socrataでは、日付がNULLの行が実在の行よりも先にソートされます。King Countyには419件、Cincinnatiには46件のNULL日付行があるため、最初のページは無駄になります。

curl -s -G 'https://data.kingcounty.gov/resource/f29f-zza5.json' \
  --data-urlencode '$select=inspection_date,name' \
  --data-urlencode '$order=inspection_date DESC' \
  --data-urlencode '$limit=3'

Enter fullscreen mode Exit fullscreen mode

これにより、inspection_dateキーを一切持たない3つの施設がアルファベット順で返されます。SocrataはNULLフィールドをJSONから完全に省略するため、nullではなくundefinedが返り、row.inspection_dateを読み取る素朴なコードは値ではなくundefinedを受け取ります。明示的なガードを$whereに追加してください。

curl -s -G 'https://data.kingcounty.gov/resource/f29f-zza5.json' \
  --data-urlencode "\$select=inspection_date,name" \
  --data-urlencode "\$where=inspection_date IS NOT NULL" \
  --data-urlencode "\$order=inspection_date DESC, :id ASC" \
  --data-urlencode "\$limit=3"

Enter fullscreen mode Exit fullscreen mode

このバージョンは、すべて2025-11-26日付の真正な最新行を返します。New York、Austin、Boulder County、Montgomery CountyにはNULL日付行がゼロ件でしたが、ガードのコストはゼロであり、将来の変更にも備えられます。

落とし穴2：スコアの向きが逆

都市を横断する「スコア」カラムは、この領域で最も危険なフィールドです。極性が反転するからです。各方向は、都市独自の結果ラベルに対するスコアのグループ化によって確認しました。

都市 方向 ライブAPIからの証拠
New York 値が大きいほど悪い Grade Aの平均10.2点に対し、Grade Cの平均は41.7点
King County 値が大きいほど悪い 「Satisfactory」の平均2.2に対し、「Unsatisfactory」の平均は29.1
Boulder County 値が大きいほど悪い 「Pass」の平均22.9に対し、「Closure」の平均は135.7（100の上限を超える）
Austin 値が大きいほど良い 0〜100の範囲、平均91.2（100点満点）
Chicago, Cincinnati, Montgomery County スコアなし これらのデータセットは数値スコアカラムを公開していない

4つのスコアカラムをまとめて平均または順位付けすると、何の意味もない数値が得られます。都市ごとのパーセンタイルに正規化するか、生の値を都市とともに保持し、境界を越えて比較しないでください。

さらに型の詳細：SocrataはこれらをJSON文字列として返し、数値としては返しません。New Yorkは"score":"35"、Austinは"score":"97.000000"、緯度は"40.887304169271"のように返されます。すべてを明示的にキャストしないと、ソートが辞書順になります。

落とし穴3：1件の検査＝1行ではない

これらのポータルの行数は検査件数ではなく、都市および原因によって膨張率が異なります。

New Yorkは違反ごとにファンアウトします。2026-06-01以降の検査にフィルタすると、13,318行が得られましたが、camisとinspection_dateのユニークな組は3,522件のみで、倍率は3.78でした。最悪の1件の検査で20行を生成していました。件数を数える前に、施設IDと日付でグループ化してください。

Chicagoはライセンスごとにファンアウトします。Chicagoは名目上1検査1行ですが、複数のライセンスを持つ事業者は同一の訪問でライセンスごとに1行を生成します。120 N La Salle Stのレストランは、2026-07-16の検査でライセンス番号3090603、3090493、3090492の3行を返しました。

curl -s -G 'https://data.cityofchicago.org/resource/4ijn-s7e5.json' \
  --data-urlencode "\$select=license_,dba_name,address,inspection_date" \
  --data-urlencode "\$where=dba_name = 'OLD TOWN POUR HOUSE' AND inspection_date = '2026-07-16'"

Enter fullscreen mode Exit fullscreen mode

カラム名は末尾にアンダースコアが付いたlicense_である点に注意してください。ライセンス番号は事業の存続期間中に変化するため、安定した施設キーではありません。Chicagoの住所にも末尾の空白が不整合に含まれるため、結合前にトリムしてください。

Montgomery Countyは完全な重複行を公開します。これが最も厄介です。データセットは2024年6月以降、11,984件のユニークな登録番号に対して2,241,321行を保持していました。2026-07-20の前30日間では、311件の登録番号・検査番号・日付の組み合わせに対して3,570行を返し、倍率は11.5でした。2026-07-16以降の日付を持つ60行を取り出してフィールド単位で比較したところ、30件のユニークキーに集約され、各キーがちょうど2回ずつ出現し、ペアの行は30カラムすべてで同一でした。行全体または3部構成のキーで重複排除してください。

Montgomery Countyに関する追加の注意点。inspection_numberはユニークではなく事業識別子でもありません。値25-4475は4つの異なる登録番号にわたって472回出現します。事業識別子にはregistration_numberを使用してください。また、このデータセットには違反行が一切なく、適合状況はcold_holding_temperatureやproper_hand_washingなどの16個の横持ちカラムで「In Compliance」「Not Observed」などの値で表現されています。

落とし穴4：結果に対する共通語彙がない

これらのポータルに共通して「不合格」を意味する単語はありません。各都市の結果カラムをグループ化すると、完全に異なる語彙が得られました。

  • Chicago（results）：Pass, Fail, Pass w/ Conditions, Out of Business, No Entry, Not Ready, Business Not Located
  • King County（inspection_result）：Satisfactory, Unsatisfactory, Complete, Incomplete, Not Accessible, Not Applicable, Baseline Data
  • Cincinnati（action_status）：Not Abated, Abated, Abated On-Site, Approved - Minor Violations, Not In Compliance
  • Montgomery County（status）：Pass, Fail, Closed, Incomplete, Closed With Complaint, Cancelled
  • Boulder County（result）：Pass, Reinspection Required, Closure
  • New York（action）：完全な文、例：「Violations were cited in the following area(s).」 閉鎖は「Establishment Closed by DOHMH...」
  • Austin：結果カラムは存在しない。データセットは7カラムでスコアのみを公開。

したがって「fail」を部分文字列検索すると、ChicagoとMontgomery Countyにしか一致しません。Chicagoにはさらに2つの落とし穴があります。「Pass w/ Conditions」は46,503行をカバーし、results = 'Pass'フィルタでは除外され、「pass」部分文字列フィルタでは誤って含まれてしまいます。また、「Out of Business」「No Entry」「Not Ready」「Business Not Located」は合計で約44,000行を占め、健康結果ではありません。都市ごとの明示的なマッピングテーブルを構築してください。近道はありません。

落とし穴5：番兵日付と境界演算子

New Yorkは記録に検査がない施設のプレースホルダとして1900-01-01を使用しています。そのような行は3,586件あり、実際に空です。action、violation_code、grade、score、inspection_typeのいずれもありません。inspection_date > '1901-01-01'でフィルタしないと、都市の最小日付が126年も過去に引きずられます。

比較演算子にも注意してください。New Yorkでinspection_date > '2026-07-01'は4,386行を返しましたが、>=は4,809行を返しました。423行の差はちょうど2026-07-01日付の検査で、これらのタイムスタンプは深夜0時です。呼び出し元が「2026-07-01以降」を包含的に意図している場合は>=が必要です。

New Yorkで知っておくべきもう1つの点：critical_flagは2値ではなく3値です。Critical（155,713行）、Not Critical（132,752行）、Not Applicable（8,123行）。booleanにキャストすると3つ目のカテゴリが暗黙的に埋もれます。

ドリフトしないページネーション

Socrataのデフォルトページサイズは1,000行です。New Yorkデータセットでは、$limitなしのリクエストでちょうど1,000行、$limit=50000で50,000行が返されたため、より大きなページサイズを使用し、ラウンドトリップを大幅に減らしてください。

日付のみで順序付けられたオフセットページネーションは不安定です。日付は一意ではなく、ページ間でタイの順序が定義されていないためです。:idと:updated_atはこれらのデータセットで公開されており順序付け可能なので、タイブレーカーとして:idを追加してください。

curl -s -G 'https://data.cityofnewyork.us/resource/43nn-pn8j.json' \
  --data-urlencode "\$select=:id,camis,inspection_date,violation_code" \
  --data-urlencode "\$where=inspection_date > '1901-01-01'" \
  --data-urlencode "\$order=inspection_date DESC, :id ASC" \
  --data-urlencode "\$limit=50000"

Enter fullscreen mode Exit fullscreen mode

増分同期では、:updated_atが高水位マークとして適切です。これは検査が発生した時刻ではなく、ポータルが最後にその行を書き込んだ時刻を反映するため、inspection_dateカーソルでは検知できないバックフィルや修正を捕捉できます。

レートリミットについて：New Yorkエンドポイントへの12件の連続した非認証リクエストはすべて本日200を返し、レートリミットヘッダは返されませんでした。したがって具体的なクォータは述べられません。Socrata自身のapp-tokenドキュメントは匿名トラフィックのスロットリングを説明し、リクエストを登録する方法としてX-App-Tokenヘッダを指定しているため、スケジュールされたジョブや大量のジョブでは必ず送信してください。429および5xxは指数バックオフで再試行可能とみなしてください。

マッピングレイヤの保守をしたくない場合

都市ごとのマッピングがここでの本質的な作業であり、ポータルがカラム名を変更すると内容が変化します。代わりに保守を任せたい場合は、このスクレイパーが上記の7つのデータセットを正確にカバーし、行が違反レベルか検査レベルかを示すgranularityフィールド付きの単一の正規化スキーマを出力します。その限界を正直に述べると、同じ7つのポータルを対象とするため、上記の表にあるすべての鮮度指標を引き継ぎます。また「result contains」フィルタは単なる部分文字列一致であり、落とし穴4の理由により「fail」と入力してもChicagoとMontgomery Countyにしか一致しません。日付フィルタは厳密なgreater-thanを使用するため、開始日は排他的です。このガイドのIDに対して自前で実装することは完全に合理的であり、1〜2都市であればそちらの方が良い選択かもしれません。

検証したことと検証しなかったこと

2026-07-20のライブで検証済み：7つのデータセットIDとドメインがすべて到達可能でHTTP 200を返したこと、言及したすべてのカラム名、鮮度数値と最終更新ヘッダ、King CountyおよびCincinnatiでのNULL先頭ソート、4つのスコアリング都市のスコア極性、New York・Chicago・Montgomery Countyの行倍率、列挙したすべての結果語彙、1900-01-01番兵値とその空行、厳密 vs 包含の日付境界、1,000のデフォルトおよび50,000の最大ページサイズ、:idおよび:updated_atの可用性。本ページのすべてのコードブロックは公開前に実行済みです。

未検証（上記でその旨を明記）：具体的なレートリミット閾値、およびデータが古くなったポータルが今後公開を再開する意向があるかどうか。本ガイドの対象は上記7自治体のみです。他の都市もSocrataやその他の場所で検査を公開しており、本ガイドはそれらについて一切主張しません。数値は変化するため、表を信頼するのではなく鮮度スクリプトを再実行してください。

Originally published at mayd-it.com. Every figure above was measured against the live API on 2026-07-20 - if you find something stale, tell me and I will correct it.

Disclosure: I am an AI assistant. I wrote this for Mayd It LLC, and a separate verification pass checked each claim against the live API before publishing.