openapi: 3.1.0 info: title: Borough NYC Real Estate API description: | Search NYC rental and sale listings, get property details, building data, and neighborhood market statistics across all five boroughs. Authentication: Pass your Borough API key as a Bearer token. version: 1.0.0 servers: - url: https://borough.qwady.app/v1 description: Production security: - BearerAuth: [] paths: /search/rentals: get: operationId: searchRentals summary: Search rental listings in NYC description: > Search active rental listings across all five NYC boroughs. Filter by neighborhood, price range, bedrooms, bathrooms, building type, and no-fee status. Returns up to 50 results per page with address, price, beds/baths, and listing URL. parameters: - name: areas in: query description: >- Comma-separated area IDs. Borough IDs: Manhattan=100, Bronx=200, Brooklyn=300, Queens=400, Staten Island=500. Use the listAreas endpoint to find neighborhood IDs. schema: type: string - name: minPrice in: query description: Minimum monthly rent in USD schema: type: integer - name: maxPrice in: query description: Maximum monthly rent in USD schema: type: integer - name: minBeds in: query description: Minimum bedrooms (0 = studio) schema: type: integer - name: maxBeds in: query description: Maximum bedrooms schema: type: integer - name: minBaths in: query description: Minimum full bathrooms schema: type: integer - name: maxBaths in: query description: Maximum full bathrooms schema: type: integer - name: buildingType in: query description: >- Comma-separated building types: RENTAL, CONDO, CO_OP, HOUSE, MULTI_FAMILY, TOWNHOUSE schema: type: string - name: noFee in: query description: Filter for no-fee listings only (no broker fee) schema: type: boolean - name: sort in: query description: Sort field schema: type: string enum: - PRICE - LISTED_AT - RECOMMENDED - name: sortDir in: query description: Sort direction schema: type: string enum: - ASC - DESC - name: hasOpenHouse in: query description: Filter for listings with scheduled open houses schema: type: boolean - name: has3dTour in: query description: Filter for listings with 3D virtual tours schema: type: boolean - name: fiberOnly in: query description: >- Require a building-level FCC broadband provider match with fiber technology. Provisional while Borough validates the underlying FCC and CostQuest contract path for further rollout. schema: type: boolean - name: minDownloadMbps in: query description: >- Require a building-level FCC broadband provider with at least this advertised download speed in Mbps. Provisional while Borough validates the underlying FCC and CostQuest contract path for further rollout. schema: type: integer - name: page in: query description: Page number (1-indexed, default 1) schema: type: integer - name: perPage in: query description: Results per page (default 10, max 50) schema: type: integer responses: '200': description: Paginated list of rental listings content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string address: type: object properties: street: type: string unit: type: string city: type: string state: type: string zipCode: type: string price: type: integer bedroomCount: type: integer fullBathroomCount: type: integer halfBathroomCount: type: integer buildingType: type: string areaName: type: string status: type: string urlPath: type: string daysOnMarket: type: integer meta: type: object properties: total: type: integer page: type: integer perPage: type: integer dataAge: type: string source: type: string /search/sales: get: operationId: searchSales summary: Search sale listings in NYC description: > Search active for-sale listings across all five NYC boroughs. Supports all rental filters plus saleType (resale, sponsor unit, foreclosure). parameters: - name: areas in: query description: >- Comma-separated area IDs. Borough IDs: Manhattan=100, Bronx=200, Brooklyn=300, Queens=400, Staten Island=500. schema: type: string - name: minPrice in: query description: Minimum sale price in USD schema: type: integer - name: maxPrice in: query description: Maximum sale price in USD schema: type: integer - name: minBeds in: query description: Minimum bedrooms (0 = studio) schema: type: integer - name: maxBeds in: query description: Maximum bedrooms schema: type: integer - name: buildingType in: query description: >- Comma-separated building types: CONDO, CO_OP, HOUSE, MULTI_FAMILY, TOWNHOUSE schema: type: string - name: saleType in: query description: 'Sale type filter: RESALE, SPONSOR_UNIT, FORECLOSURE' schema: type: string enum: - RESALE - SPONSOR_UNIT - FORECLOSURE - name: fiberOnly in: query description: >- Require a building-level FCC broadband provider match with fiber technology. Provisional while Borough validates the underlying FCC and CostQuest contract path for further rollout. schema: type: boolean - name: minDownloadMbps in: query description: >- Require a building-level FCC broadband provider with at least this advertised download speed in Mbps. Provisional while Borough validates the underlying FCC and CostQuest contract path for further rollout. schema: type: integer - name: sort in: query description: Sort field schema: type: string enum: - PRICE - LISTED_AT - RECOMMENDED - name: sortDir in: query description: Sort direction schema: type: string enum: - ASC - DESC - name: page in: query description: Page number (1-indexed, default 1) schema: type: integer - name: perPage in: query description: Results per page (default 10, max 50) schema: type: integer responses: '200': description: Paginated list of sale listings content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string address: type: object properties: street: type: string unit: type: string city: type: string state: type: string zipCode: type: string price: type: integer bedroomCount: type: integer fullBathroomCount: type: integer buildingType: type: string areaName: type: string status: type: string urlPath: type: string meta: type: object properties: total: type: integer page: type: integer perPage: type: integer /property/{id}: get: operationId: getProperty summary: Get full listing detail description: | Full listing detail with 50+ fields including pricing, fees, amenities, photos, agent info, and price history. Requires Starter plan or higher. parameters: - name: id in: path required: true description: Listing ID (numeric string) schema: type: string responses: '200': description: Full listing detail content: application/json: schema: type: object properties: data: type: object properties: id: type: string address: type: object properties: street: type: string unit: type: string city: type: string state: type: string zipCode: type: string price: type: integer netEffective: type: integer description: Monthly rent after concessions monthsFree: type: integer bedroomCount: type: integer fullBathroomCount: type: integer sqft: type: integer buildingType: type: string areaName: type: string status: type: string noFee: type: boolean petsAllowed: type: boolean amenities: type: array items: type: object properties: name: type: string available: type: boolean urlPath: type: string daysOnMarket: type: integer internetProviders: type: - object - 'null' description: >- Provisional FCC-backed building-level availability block pending contract validation for the underlying FCC and CostQuest access path. properties: status: type: string enum: - matched - unmatched - error source: type: string enum: - fcc_bdc coverageLevel: type: string enum: - building fccLocationId: description: >- Current Borough response field for the matched FCC location identifier. This field is provisional and may change shape in a future revision. type: - integer - 'null' matchedAddress: type: - string - 'null' unitCount: type: - integer - 'null' updatedAt: type: - string - 'null' providers: type: array items: type: object properties: providerId: type: integer providerName: type: string holdingCompanyName: type: - string - 'null' technologyCode: type: integer technologyLabel: type: string maxDownloadMbps: type: - integer - 'null' maxUploadMbps: type: - integer - 'null' lowLatency: type: - boolean - 'null' disclaimer: type: string meta: type: object properties: dataAge: type: string source: type: string '404': description: Listing not found /property/by-url: get: operationId: getPropertyByUrl summary: Look up listing by URL path description: > Find a listing using its URL path (e.g., /building/one57-condominium/48b). Requires Starter plan or higher. parameters: - name: url in: query required: true description: Listing URL path (e.g., /building/one57-condominium/48b) schema: type: string responses: '200': description: Full listing detail (same schema as getProperty) content: application/json: schema: type: object properties: data: type: object meta: type: object '404': description: Listing not found /building/{id}: get: operationId: getBuilding summary: Get building detail description: | Comprehensive building data including amenities, policies, developer, architect, NYC regulatory data, and inventory summaries. Requires Starter plan or higher. parameters: - name: id in: path required: true description: Building ID or slug schema: type: string responses: '200': description: Full building detail content: application/json: schema: type: object properties: data: type: object properties: id: type: string name: type: string slug: type: string type: type: string yearBuilt: type: integer floorCount: type: integer unitCount: type: integer address: type: object properties: street: type: string city: type: string state: type: string zipCode: type: string amenities: type: object properties: list: type: array items: type: string policies: type: object properties: list: type: array items: type: string petPolicy: type: object properties: catsAllowed: type: boolean dogsAllowed: type: boolean internetProviders: type: - object - 'null' description: >- Provisional FCC-backed building-level availability block pending contract validation for the underlying FCC and CostQuest access path. properties: status: type: string enum: - matched - unmatched - error source: type: string enum: - fcc_bdc coverageLevel: type: string enum: - building fccLocationId: description: >- Current Borough response field for the matched FCC location identifier. This field is provisional and may change shape in a future revision. type: - integer - 'null' matchedAddress: type: - string - 'null' unitCount: type: - integer - 'null' updatedAt: type: - string - 'null' providers: type: array items: type: object properties: providerId: type: integer providerName: type: string holdingCompanyName: type: - string - 'null' technologyCode: type: integer technologyLabel: type: string maxDownloadMbps: type: - integer - 'null' maxUploadMbps: type: - integer - 'null' lowLatency: type: - boolean - 'null' disclaimer: type: string meta: type: object '404': description: Building not found /building/{id}/listings: get: operationId: getBuildingListings summary: Get listings in a building description: | All active (or filtered) listings within a specific building. Requires Starter plan or higher. parameters: - name: id in: path required: true description: Building ID or slug schema: type: string - name: status in: query description: Filter by listing status schema: type: string enum: - ACTIVE - IN_CONTRACT - OFF_MARKET - name: type in: query description: Filter by listing type schema: type: string enum: - rental - sale - name: page in: query schema: type: integer - name: perPage in: query schema: type: integer responses: '200': description: Paginated list of listings in building content: application/json: schema: type: object properties: data: type: array items: type: object meta: type: object properties: total: type: integer page: type: integer perPage: type: integer /areas: get: operationId: listAreas summary: List NYC areas and neighborhoods description: > Returns all 349 NYC areas including boroughs, sub-boroughs, and neighborhoods. Use area IDs in search filters. No authentication required. security: [] parameters: - name: level in: query description: 'Filter by hierarchy level: 0=borough, 1=sub-borough, 2=neighborhood' schema: type: integer enum: - 0 - 1 - 2 - name: parentId in: query description: >- Filter by parent area ID (100=Manhattan, 200=Bronx, 300=Brooklyn, 400=Queens, 500=Staten Island) schema: type: integer responses: '200': description: List of areas content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: integer name: type: string level: type: integer description: 0=borough, 1=sub-borough, 2=neighborhood parentId: type: integer slug: type: string meta: type: object properties: total: type: integer /market/rentals/snapshot: get: operationId: getMarketSnapshot summary: Get market snapshot for an area description: | Pre-computed market statistics for a specific area: active inventory, median rent, average days on market, and concession rate. Snapshots are recomputed daily. Requires Starter plan or higher. parameters: - name: areaId in: query required: true description: Area ID (use listAreas to find IDs) schema: type: integer - name: bedrooms in: query description: Filter by bedroom count (0=studio, 1-4) schema: type: integer - name: listingType in: query description: Listing type schema: type: string enum: - rental - sale responses: '200': description: Market snapshot data content: application/json: schema: type: object properties: data: type: array items: type: object properties: areaId: type: integer bedrooms: type: integer listingType: type: string inventory: type: integer description: Count of active listings medianRent: type: number description: Median asking price avgDaysOnMarket: type: number concessionRate: type: number description: Fraction of listings offering concessions (0.0-1.0) meta: type: object /market/rentals/trends: get: operationId: getMarketTrends summary: Get market trends for an area description: | Price event time series for an area. Returns up to 365 days of data. Useful for charting price movement and listing activity. Requires Starter plan or higher. parameters: - name: areaId in: query required: true description: Area ID schema: type: integer - name: listingType in: query description: Listing type schema: type: string enum: - rental - sale responses: '200': description: Time series of price events content: application/json: schema: type: object properties: data: type: array items: type: object properties: date: type: string event: type: string avgPrice: type: number count: type: integer meta: type: object /market/compare: get: operationId: compareMarkets summary: Compare market snapshots across areas description: | Side-by-side market snapshots for up to 5 areas. Returns snapshot data grouped by area ID. Requires Starter plan or higher. parameters: - name: areas in: query required: true description: Comma-separated area IDs (1-5) schema: type: string - name: bedrooms in: query description: Filter by bedroom count (0=studio, 1-4) schema: type: integer - name: listingType in: query description: Listing type schema: type: string enum: - rental - sale responses: '200': description: Market comparison data content: application/json: schema: type: object properties: data: type: array items: type: object properties: areaId: type: integer snapshots: type: array items: type: object properties: bedrooms: type: integer inventory: type: integer medianRent: type: number avgDaysOnMarket: type: number concessionRate: type: number meta: type: object /health: get: operationId: healthCheck summary: Health check description: Public uptime check. Returns service status. security: [] responses: '200': description: Service healthy content: application/json: schema: type: object properties: status: type: string timestamp: type: string components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: BOROUGH- description: >- Borough API key. Format: BOROUGH-. Get one free at https://docs.qwady.app/tiers-and-pricing