redfin-api

Redfin API

Redfin は https://www.redfin.com/stingray/ で非公式の JSON API を提供しています。すべての リクエストは HTTP GET です。レスポンスは有効な JSON の前に {}& （4 バイト）が付加されます。 解析する前に、必ずこのプレフィックスを取り除いてください。

認証とヘッダー

• User-Agent ヘッダーは必須です（最新の Chrome UA 文字列を使用してください）
• 認証が必要なアクセスでは、任意で次の Cookie を指定できます：
  • RF_ACCESS_LEVEL、RF_AUTH、RF_W_AUTH、RF_SECURE_AUTH、RF_PARTY_ID
• ブロックを避けるため、リクエスト間にレート制限用の間隔を設けてください

レスポンス形式

すべてのエンドポイントは次のラッパーを返します：

{
  "version": 1,
  "errorMessage": "Success",
  "resultCode": 0,
  "payload": { ... }
}

resultCode == 0 かつ errorMessage == "Success" は成功を示します。 payload の構造はエンドポイントによって異なります。

主なワークフロー

1. 郵便番号／場所から物件を検索する

ステップ 1：場所のオートコンプリートで地域 ID を取得します。

GET /stingray/do/location-autocomplete?location={query}&v=2

レスポンスの payload：

{
  "sections": [{ "rows": [{ "id": "2_12345", "type": "2", "name": "92708", ... }] }],
  "exactMatch": { "id": "2_12345", ... }
}

id フィールドは {region_type}_{region_id} の形式です。_ で分割して両方を抽出します。

ステップ 2：GIS CSV のダウンロードで、その地域の物件情報を取得します。

GET /stingray/api/gis-csv?region_id={id}&region_type={type}&...

CSV データが返されます（JSON ではないため、{}& プレフィックスはありません）。CSV の内容：

• 行 0：ヘッダー（URL 列を探してください）
• 行 1：MLS の免責事項テキスト（「In accordance with local MLS rules...」）
• 行 2 以降：物件データ

URL 列を抽出して、以降のクエリで使用する Redfin の物件 URL を取得します。

2. URL から物件 ID を取得する

GET /stingray/api/home/details/initialInfo?path={redfin_path}

path は URL のパス部分です（例：/CA/Fountain-Valley/12345-Main-St-92708/home/12345678）。

ペイロード：

{
  "propertyId": 12345678,
  "listingId": 234567890,
  "latLong": { "latitude": 33.71, "longitude": -117.95 }
}

3. 物件の詳細を取得する

詳細エンドポイントの大半は /stingray/api/home/details/ 配下にあります。propertyId のみが必要なものと、propertyId と listingId の両方が必要なものがあります。

物件のみを対象とするエンドポイントでは、accessLevel=1 を追加し、必要に応じて pageType=3 を指定します。

エンドポイント一覧

URL ベース（path パラメーターを指定）

エンドポイント	パス
初期情報	api/home/details/initialInfo
ページタグ	api/home/details/v1/pagetagsinfo
主要地域	api/home/details/primaryRegionInfo

検索

エンドポイント	パス	主なパラメーター
場所のオートコンプリート	do/location-autocomplete	location、v=2
GIS CSV	api/gis-csv	region_id、region_type、フィルター（以下を参照）

物件 ID のみ（propertyId パラメーター）

エンドポイント	パス	ページタイプ
折り返しより下（MLS）	api/home/details/belowTheFold	3
周辺の写真	api/home/details/hood-photos	—
その他のリソース	api/home/details/moreResourcesInfo	—
ページヘッダー	api/home/details/homeDetailsPageHeaderInfo	—
物件に関するコメント	api/v1/home/details/propertyCommentsInfo	—
建物の詳細	api/building/details-page/v1	—
所有者査定額	api/home/details/owner-estimate	—
売主申告データ	api/home/details/claimedHomeSellerData	—
所有コスト	do/api/costOfHomeOwnershipDetails	—

リスティング ID のみ（listingId パラメーター）

エンドポイント	パス
間取り	api/home/details/listing/floorplans
内見日時選択	do/tourlist/getDatePickerData

テーブル ID（tableId パラメーター）

エンドポイント	パス	追加パラメーター
共有地域	api/region/shared-region-info	regionTypeId=2、mapPageTypeId=1

物件の詳細情報（propertyId + listingId パラメーター）

エンドポイント	パス	ページタイプ
類似物件	api/home/details/similars/listings	—
類似の売却済み物件	api/home/details/similars/solds	—
近隣の住宅	api/home/details/nearbyhomes	—
ファーストビュー	api/home/details/aboveTheFold	—
物件区画	api/home/details/propertyParcelInfo	3
アクティビティ／履歴	api/home/details/activityInfo	—
オフマーケット情報	api/home/details/customerConversionInfo/offMarket	3
賃料の推定額	api/home/details/rental-estimate	—
AVM の履歴	api/home/details/avmHistoricalData	—
情報パネル	api/home/details/mainHouseInfoPanelInfo	—
説明	api/home/details/descriptiveParagraph	—
AVM の詳細	api/home/details/avm	—
内覧インサイト	api/home/details/tourInsights	3
統計	api/home/details/stats	regionId も必要

GISCSV のデフォルトパラメーター

これらのデフォルト値を使うと、指定した地域の幅広い物件情報を取得できます。検索ごとに region_id と region_type を上書きしてください。

DEFAULT_GISCSV_PARAMS = {
    "al": "3",
    "num_homes": "350",
    "ord": "redfin-recommended-asc",
    "page_number": "1",
    "region_id": "",          # required — from location autocomplete
    "region_type": "2",       # 2 = zipcode
    "sf": "1,2,5,6,7",       # property sub-filters
    "status": "9",            # 9 = all statuses
    "uipt": "1,2,3,4,5,6,7,8",  # all property types
    "v": "8",
    # boolean filters (all false for broadest results)
    "has_pool": "false",
    "has_parking": "false",
    "has_laundry_facility": "false",
    "has_laundry_hookups": "false",
    "has_dishwasher": "false",
    "has_att_fiber": "false",
    "has_deal": "false",
    "has_short_term_lease": "false",
    "include_pending_homes": "false",
    "isRentals": "false",
    "is_furnished": "false",
    "is_income_restricted": "false",
    "is_senior_living": "false",
    "pool": "false",
    "travel_with_traffic": "false",
    "travel_within_region": "false",
    "utilities_included": "false",
}

一戸建てのみで絞り込む

一戸建てに限定するには（このプロジェクトに該当します）：

• uipt=1 を設定します（1,2,3,4,5,6,7,8 ではなく、一戸建てのみ）。
• sf=1,2,5,6,7 を設定します（デフォルトのサブフィルターを維持します）。

物件タイプコード（uipt）

コード	タイプ
1	一戸建て
2	コンドミニアム
3	タウンハウス
4	集合住宅
5	土地
6	モバイル／プレハブ住宅
7	コーポラティブ住宅
8	その他

レスポンスペイロードの解析

Redfin のペイロードは深くネストされています。データの抽出には、JMESPath 式（または同等の 辞書の走査）を使用します。

InitialInfo ペイロードから

フィールド	JMESPath
物件 ID	propertyId
掲載 ID	listingId
緯度	latLong.latitude
経度	latLong.longitude

BelowTheFold（MLS）ペイロードから

フィールド	JMESPath
郵便番号	publicRecordsInfo.addressInfo.zip
市	publicRecordsInfo.addressInfo.city
州	publicRecordsInfo.addressInfo.state
画像 URL	propertyHistoryInfo.mediaBrowserInfoBySourceId.*.photos[].photoUrls.nonFullScreenPhotoUrlCompressed
サムネイル URL	propertyHistoryInfo.mediaBrowserInfoBySourceId.*.photos[].thumbnailData.thumbnailUrl
不動産仲介業者のクレジット表記	propertyHistoryInfo.mediaBrowserInfoBySourceId.*.photoAttribution | [0]
イベント数	length(propertyHistoryInfo.events)
イベント価格	propertyHistoryInfo.events[N].price
イベントの説明	propertyHistoryInfo.events[N].eventDescription
イベントのソース	propertyHistoryInfo.events[N].source
イベントのソース ID	propertyHistoryInfo.events[N].sourceId
イベントの日付	propertyHistoryInfo.events[N].eventDate（Unix ミリ秒）

不動産仲介業者名の解析

photoAttribution フィールドは "Listed by Jane Smith • Acme Realty." のような形式です。 • で分割し、空白を削除します。パート 0 から "Listed by " を削除し、パート 1 の 末尾にある . を削除します。

イベント日付の処理

イベントの日付は Unix タイムスタンプ（ミリ秒）です。次のように変換します。 datetime.fromtimestamp(event_date / 1000)（Python）または time.Unix(0, event_date * int64(time.Millisecond))（Go）。

住宅購入に特に役立つエンドポイント

物件の評価には、次の 3 つが最も役立ちます。

1. InitialInfo — 物件 ID／掲載 ID、緯度／経度
2. BelowTheFold — 住所、物件履歴（価格の変動）、画像、不動産仲介業者の情報
3. AVMDetails — Redfin の自動評価モデルによる推定額

その他、特に役立つエンドポイント：

• SimilarSold — 最近の類似物件の売却情報
• SimilarListings — 競合する掲載物件
• CostOfHomeOwnership — 月々の推定費用の内訳
• Activity — 内覧、保存、閲覧のアクティビティ
• Stats — 地域の市場統計

実装上の注意点

レスポンスプレフィックスの除去

GISCSV が生の CSV を返す場合を除き、すべてのレスポンスには {}& （正確に 4 バイト）がプレフィックスとして付加されています。JSON を解析する前に取り除いてください。

// Go
jsonBytes := responseBytes[4:]

# Python
data = json.loads(response.text[4:])

レート制限

リクエストの間に遅延を設けてください（gredfin プロジェクトでは設定可能な間隔を使用しており、通常は数秒です）。Redfin は過度なスクレイピングをブロックします。

エラー処理

HTTP ステータスコードと、JSON レスポンス内の resultCode／errorMessage フィールドの両方を必ず確認してください。HTTP ステータスが 200 でも、Redfin のレスポンス本文にエラーが含まれている場合があります。

ハッシュベースの重複排除

物件を一定期間ポーリングする際は、ペイロードのバイト列をハッシュ（MD5）化し、前回のスクレイピング時から変更がなければ再処理をスキップしてください。