贝壳 API - 二手房房源列表 (V1)

prod-global

GET

/api/beike/get-ershoufang-list/v1

根据指定筛选条件获取贝壳（链家）的二手房房源列表。

主要功能：

支持按城市/区域、价格区间、户型、面积进行筛选。
返回房源核心信息，如标题、总价、单价及小区信息。
提供房源编码，可通过详情接口获取完整信息。

典型应用场景：

为房产门户网站构建搜索结果页面。
聚合区域房价趋势的市场数据。

请求参数

参数名	位置	类型	必填	说明
`token`	query	`string`	是	用户鉴权令牌。
`cityId`	query	`string`	是	城市ID（例如，北京为'110000'）。
`condition`	query	`string`	否	筛选条件（例如：区域、价格范围、户型）。
`offset`	query	`integer`	否	分页偏移量，从0开始（例如：0、20、40...）。

代码示例

💡 环境说明

默认示例使用 https://api.justoneapi.com (prod-global)。中国大陆地区建议替换为 http://47.117.133.51:30015 (prod-cn) 以获得更好的访问体验。详见环境选择。

bash

# 提示: 中国大陆地区建议将 https://api.justoneapi.com 替换为 http://47.117.133.51:30015
curl -X GET "https://api.justoneapi.com/api/beike/get-ershoufang-list/v1?token=YOUR_API_KEY&cityId=VALUE"

text

我想使用 Just One API 提供的“二手房房源列表 (V1)”接口。
接口地址: https://api.justoneapi.com/api/beike/get-ershoufang-list/v1
HTTP 方法: GET
身份验证: 在 URL 后添加查询参数“?token=您的API密钥”。
OpenAPI 定义: https://docs.justoneapi.com/openapi/beike-apis/resale-housing-list-v1-zh.json

请求参数说明:
- token (query): 用户鉴权令牌。 (必填)
- cityId (query): 城市ID（例如，北京为'110000'）。 (必填)
- condition (query): 筛选条件（例如：区域、价格范围、户型）。
- offset (query): 分页偏移量，从0开始（例如：0、20、40...）。

返回格式: JSON

响应处理与错误码：
1. 需通过返回体中的 "code" 字段判断业务结果（code 为 0 表示成功）。
2. 超时建议：建议将请求超时时间设置为至少 60 秒。
3. 业务码说明：
   - 0: 成功
   - 100: Token 无效或已失效
   - 301: 采集失败，请重试
   - 302: 超出速率限制
   - 303: 超出每日配额
   - 400: 参数错误
   - 500: 内部服务器错误
   - 600: 权限不足
   - 601: 余额不足

请帮我用我擅长的编程语言写一个脚本来调用这个接口，并处理返回结果。

python

# 提示: 中国大陆地区建议将 https://api.justoneapi.com 替换为 http://47.117.133.51:30015
import requests

url = "https://api.justoneapi.com/api/beike/get-ershoufang-list/v1?token=YOUR_API_KEY&cityId=VALUE"
response = requests.get(url)
print(response.json())

// 提示: 中国大陆地区建议将 https://api.justoneapi.com 替换为 http://47.117.133.51:30015
const response = await fetch("https://api.justoneapi.com/api/beike/get-ershoufang-list/v1?token=YOUR_API_KEY&cityId=VALUE", {
  method: "GET"
});
const data = await response.json();
console.log(data);

java

// 提示: 中国大陆地区建议将 https://api.justoneapi.com 替换为 http://47.117.133.51:30015
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.justoneapi.com/api/beike/get-ershoufang-list/v1?token=YOUR_API_KEY&cityId=VALUE"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

// 提示: 中国大陆地区建议将 https://api.justoneapi.com 替换为 http://47.117.133.51:30015
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	client := &http.Client{}
	url := "https://api.justoneapi.com/api/beike/get-ershoufang-list/v1?token=YOUR_API_KEY&cityId=VALUE"
	req, _ := http.NewRequest("GET", url, nil)
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

php

// 提示: 中国大陆地区建议将 https://api.justoneapi.com 替换为 http://47.117.133.51:30015
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.justoneapi.com/api/beike/get-ershoufang-list/v1?token=YOUR_API_KEY&cityId=VALUE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$response = curl_exec($ch);
curl_close($ch);
echo $response;

[OpenAPI 定义 (JSON)]

响应结果

json

{
  "code": 0,
  "data": {
    "request_id": "dd9a1e0e-1bc0-11f1-8335-ba5e53120619",
    "uniqid": "1055-5AE4-9BAD-7E42-6B9B97F1E7C3",
    "errno": 0,
    "error": "",
    "data": {
      "totalCount": 0,
      "noResultNearHouse": 0,
      "returnCount": 0,
      "hasMoreData": 0,
      "headerList": [
        {
          "filters": {
            "checkFilters": {
              "region": {
                "name": "区域",
                "type": 0,
                "options": [
                  {
                    "name": "区域",
                    "itemType": "district",
                    "type": 0,
                    "alias": "d",
                    "options": [
                      {
                        "name": "不限",
                        "type": 0,
                        "options": [
                          {
                            "name": "不限"
                          }
                        ]
                      }
                    ]
                  }
                ]
              },
              "price": {
                "name": "价格",
                "itemType": "totalPrice",
                "type": 1,
                "alias": "p",
                "range": {
                  "name": "自定义价格",
                  "min": {
                    "name": "最低总价",
                    "key": "bp"
                  },
                  "max": {
                    "name": "最高总价",
                    "key": "ep"
                  },
                  "slide": {
                    "length": 10000000,
                    "step": 100000,
                    "minText": "0元",
                    "maxText": "1000万以上"
                  },
                  "rangeUnit": {
                    "default": "万",
                    "less": "万以下",
                    "more": "万以上"
                  },
                  "rangeUnitLow": {
                    "default": "元",
                    "less": "元以下",
                    "more": "元以上"
                  }
                },
                "options": [
                  {
                    "name": "200万以下",
                    "id": 1,
                    "key": "p1",
                    "left": 0,
                    "right": 2000000
                  }
                ]
              },
              "room": {
                "name": "房型",
                "itemType": "room_count",
                "type": 1,
                "alias": "l",
                "options": [
                  {
                    "name": "一室",
                    "id": 1,
                    "key": "l1"
                  }
                ]
              },
              "area": {
                "name": "建筑面积",
                "itemType": "house_area",
                "type": 1,
                "alias": "a",
                "range": {
                  "name": "自定义建筑面积",
                  "min": {
                    "name": "最小",
                    "key": "ba"
                  },
                  "max": {
                    "name": "最大",
                    "key": "ea"
                  },
                  "slide": {
                    "length": 200,
                    "step": 5,
                    "minText": "0㎡",
                    "maxText": "200㎡以上"
                  },
                  "rangeUnit": {
                    "default": "㎡",
                    "less": "㎡以下",
                    "more": "㎡以上"
                  }
                },
                "options": [
                  {
                    "name": "50㎡以下",
                    "id": 1,
                    "key": "a1",
                    "left": 0,
                    "right": 50
                  }
                ]
              },
              "more": {
                "name": "更多",
                "type": 1,
                "options": [
                  {
                    "name": "建筑面积",
                    "itemType": "house_area",
                    "type": 1,
                    "alias": "a",
                    "range": {
                      "name": "自定义建筑面积",
                      "min": {
                        "name": "最小",
                        "key": "ba"
                      },
                      "max": {
                        "name": "最大",
                        "key": "ea"
                      },
                      "slide": {
                        "length": 200,
                        "step": 5,
                        "minText": "0㎡",
                        "maxText": "200㎡以上"
                      },
                      "rangeUnit": {
                        "default": "㎡",
                        "less": "㎡以下",
                        "more": "㎡以上"
                      }
                    },
                    "options": [
                      {
                        "name": "50㎡以下",
                        "id": 1,
                        "key": "a1",
                        "left": 0,
                        "right": 50
                      }
                    ]
                  }
                ]
              },
              "soldMore": {
                "name": "建筑面积",
                "type": 1,
                "options": [
                  {
                    "name": "建筑面积",
                    "itemType": "house_area",
                    "type": 1,
                    "alias": "a",
                    "range": {
                      "name": "自定义建筑面积",
                      "min": {
                        "name": "最小",
                        "key": "ba"
                      },
                      "max": {
                        "name": "最大",
                        "key": "ea"
                      },
                      "slide": {
                        "length": 200,
                        "step": 5,
                        "minText": "0㎡",
                        "maxText": "200㎡以上"
                      },
                      "rangeUnit": {
                        "default": "㎡",
                        "less": "㎡以下",
                        "more": "㎡以上"
                      }
                    },
                    "options": [
                      {
                        "name": "50㎡以下",
                        "id": 1,
                        "key": "a1",
                        "left": 0,
                        "right": 50
                      }
                    ]
                  }
                ]
              }
            },
            "sortFilters": [
              {
                "name": "默认排序"
              }
            ],
            "listFilters": [
              {
                "name": "满五年",
                "id": 1,
                "key": "mw1"
              }
            ]
          },
          "itemKey": "filters"
        }
      ],
      "houseTooFew": 0,
      "subscribe": 0
    },
    "cost": 58
  }
}

💡 提示：为简化展示，列表类数据样例仅保留 1-2 条记录，实际返回条数以接口响应为准。

贝壳 API - 二手房房源列表 (V1) ​

请求参数 ​

代码示例 ​

响应结果 ​

贝壳 API - 二手房房源列表 (V1)

请求参数

代码示例

响应结果