Docs

房源

最后更新: 2026-10-03阅读约 9 分钟

三种房源类型（kind）：property 出售，rental 出租，complex 住宅小区。读取免费，任何密钥都可使用；创建、编辑和删除需要 objects:write 权限范围，同样不收费。

列表

curl "https://developers.grem.capital/api/v1/objects?kind=property&city=Berlin&limit=20" \
  -H "Authorization: Bearer gsk_live_xxx"

GET /objects：

参数说明
kind必填：property、rental 或 complex；不区分大小写
city、country精确匹配筛选
priceMin、priceMax以美元计的价格（按标准化价格）
areaMin、areaMax面积，m²
rooms房间数（出售和出租）；可以是小数
type、residentialType类别：字典中的代码（出售和出租）
page页码，从 1 开始；更小的值按 1 处理
limit每页条数，默认 20，范围 1-50；超出范围的值会被限制到范围内
sortnewest（默认）或 oldest
scope仅机构密钥：默认为机构的房源；catalog 为公开目录

响应：data 为房源，paginate 包含 currentPage、totalPages、totalCount。

超出范围的 limit 和 page 会被限制到范围内，而不会被拒绝。已知参数的其他无效值（未知的枚举值、page 不是整数、用文本代替数字）以 400 validation 拒绝，并指出字段名。

单个房源

GET /objects/{kind}/{id}：同样格式的单个房源。未知 ID：404。机构密钥可以加上 scope=catalog 获取公开视图。

房源格式

字段说明
id、kind、name、slug标识
status他人的房源：active 或 sold
type类别：代码
price、currency价格；小区为 price: { from, to, currency }
constructionYear建造年份，整数或 null
address完整地址，含街道和坐标
nativeAreaUnit房源录入时使用的单位（用于显示）；面积以 { "value": 50, "unit": "m2" } 返回
photos照片：id、isMain、mimetype、variants、ready
processingStatusready、processing 或 failed：照片是否就绪
promoted房源正在推广
author房源的经纪人或机构

类别和其他属性都是代码；翻译后的标签见字典。小区还有 apartmentPlans（户型）和 progress（施工进度）。

照片的 ready: false 表示带水印的变体仍在生成。请显示占位图，稍后重新读取房源；不要缓存未完成的图片。

您能看到的内容：任意房源为公开卡片，与网站相同；您自己的房源为完整的所有者视图。任何人都拿不到所有者的联系方式、导入的卖方数据、审核备注或不带水印的原图。

创建、编辑、删除

操作请求响应
创建POST /objects/{kind}201 和房源
编辑PUT /objects/{kind}/{id}房源；仅所有者，否则 404
删除DELETE /objects/{kind}/{id}草稿永久删除，已发布房源归档；有生效中佣金合同的房源：409 conflict
curl -X POST https://developers.grem.capital/api/v1/objects/property \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9a1d2c3b-4e5f-4a6b-8c7d-0e1f2a3b4c5d" \
  -d '{
    "name": "两居室，Torstraße 12",
    "type": "Residential",
    "address": { "country": "Germany", "city": "Berlin", "street": "Torstraße", "streetNumber": "12" },
    "price": 320000, "currency": "EUR",
    "spaceAll": 64, "rooms": 2, "floor": 3, "buildingFloor": 5,
    "photos": ["https://example.com/1.jpg"],
    "publish": false
  }'
  • publish: false（默认）为草稿，不进入目录；publish: true 为发布。发布时 property 和 rental 至少需要 1 张照片，complex 需要 2 张。
  • 并非每种账户角色都能创建所有类型，与后台一致。
  • 未知字段会被忽略。类别代码请从字典获取。condition、conditionType 和 amenities 的代码（camelCase，例如 needsRenovation、fridge）列在写入 schema 本身中（下方表格和 /openapi.json），GET /dictionaries 不会解码它们。
  • 面积：以 m² 为单位的数字，或 { "value": 700, "unit": "ft2" }。
  • 不带 photos 的 PUT 会保留现有照片。
  • 创建时使用 Idempotency-Key 可防止重试产生重复。

照片

photos 是一个数组，每个元素是：

  • 公开的 https://... 地址：GREM 会自行下载图片；
  • 通过 POST /uploads 上传的文件 ID（文件）。

无法下载的地址会被跳过，并在响应的 warnings 中说明。使用 strictPhotos: true 时，这样的请求会改为以 422 失败。

出售字段

必填：name、type、address、price。

字段说明
typeResidential、Commercial、Industrial 或 Land plot
residentialType、commercialType、industrialType子类型：一个代码或代码数组
marketSegmentprimary（新房）或 secondary
description描述，最多 5000 字符
addresscountry、city（必填）、district、region、street、streetNumber、postalCode、location
price、currency价格；货币 UAH、USD、EUR、AZN、GBP、AED、CNY、TRY、GEL
constructionYear年份，1700 到 2100
spaceAll、spaceLiving、spaceKitchen、effectiveArea、auxiliaryArea、landPlotArea面积
rooms、bedrooms、numberOfBathrooms、balconies、numberWindows、unitsCount数量
floor、buildingFloor、ceilingHeight楼层、总楼层、层高
conditionneedsRenovation、partialRenovation、renovated、designer、shellCore、newFromDeveloper
buildingTypenewBuilding、secondary、stalinka、khrushchevka、brezhnevka、czech、gostinka、prerevolutionary、townhouseRow、detached、other
wallMaterialType、constructionTech、kitchenType墙体材料、建造工艺、厨房类型
amenities、buildingAmenities房屋和楼栋配套：代码数组
utilitySystem、heating、windowView、balcony、parking公用设施、供暖、景观、阳台、停车
safetyshelterNearby、powerBackup、autonomousHeating、waterReserve、starlink、gasAvailable、internetAvailable、elevatorWorks（是/否）
accessibilityramp、groundLevelEntrance、wideDoors、disabledParking、wheelchairElevator（是/否）
programseOselya、eVidnovlennya、mortgageEligible、installment
monthRentalRate、annualIncome、annualYield、paybackPeriod、propertyTax、insuranceCost、managementFee、repairsReserve投资数据
commission给经纪人的佣金：payer、type、value
tour3D 看房：kind、url
complexId该房屋所属的小区
photos、video媒体
publish、strictPhotos见上文

出租字段

必填：name、type（Residential、Commercial、Industrial）、address、price。大多数字段与出售相同；出租特有的字段：

字段说明
rentalTypelong 长租，short 日租
price、dayPrice、deposit租金、日租价、押金
totalArea、totalFloors、bathrooms面积、楼层数、卫生间
minRentTime、minTermMonths最短租期
availableFrom可入住日期
checkIn、checkOut入住和退房时间：from、to — 一天中的小时（15 = 15:00）
withChildren、withPets允许儿童；宠物：yes、no、with someone
furniture、furnitureList家具
conditionType状况：与出售的 condition 取值相同
onsiteAmenities、internalFeature配套
utilitiesIncluded、utilitiesCost水电杂费
checkInPay、onlinePay、bankTransfer、reportingDocuments支付方式和票据

小区字段

必填：name、address。

字段说明
description、descriptionPresentation、descriptionSocial描述
pricefrom、to、currency
space房屋面积：from、to
apartType房屋类型
classeconomy、comfort、comfortPlus、business、premium、elite
stageplanning、excavation、construction、finishing、commissioned、delivered
completionQuarter竣工季度
queues分期：name、stage、completionQuarter
sectionsNumber、floors、apartmentsNumber、parkingSpaces数量
installment、installmentTerms分期付款：downPaymentPct、termMonths、interestRate
infrastructure基础设施：代码数组
territoryDescription、parkingDescription、infrastructureDescription描述
apartmentPlans户型：apartType、area、price、description、photos
progress施工进度：title、date、description、photos

每种类型带全部取值的完整架构：/openapi.json 中的 ObjectWriteProperty、ObjectWriteRental、ObjectWriteComplex 组件。它们由服务器执行的同一套校验生成。

机构密钥

请求作用
PATCH /objects/{kind}/{id}/agency把房源转入机构或转回个人：请求体 {"targetAgencyId": "<id>"} 或 {"targetAgencyId": null}；不带该字段时转入密钥所属机构
PATCH /objects/{kind}/{id}/assignee指派经纪人：{"assignTo": "<user id>"}

使用个人密钥时两者都返回 403。房源不能直接从一个机构转到另一个机构（409 conflict）：请先转回个人。为个人房源指派经纪人，或指派给不是机构活跃成员的人，同样返回 409 conflict。权限：转入机构为房源作者；转回个人为经理、机构所有者或作者；指派任何人需经理及以上，经纪人只能指派自己。

事件

object.created、object.updated、object.published、object.deleted：见 Webhooks。

相关文章

这篇文章对您有帮助吗？