> ## Documentation Index > Fetch the complete documentation index at: https://qwady.wiki/llms.txt > Use this file to discover all available pages before exploring further. # List Areas > Returns the area hierarchy: 349 areas across NYC and Northern New Jersey, of which 316 are NYC neighborhoods and sub-areas and 5 are boroughs. Optionally filter by level or parent area. This route is paginated: `perPage` defaults to 10 (and is capped at 10 on the Free tier), so a single unfiltered call returns 10 of 349 rows. Read `meta.total` and page through, or raise `perPage` on a paid tier. **Tier:** Free+ ## OpenAPI ````yaml GET /areas openapi: 3.1.0 info: title: Borough API description: > NYC Real Estate Data API: structured access to rental and sale listings, building details, neighborhood data, and market statistics. ## Authentication All authenticated endpoints require a `Bearer` token in the `Authorization` header: ``` Authorization: Bearer BOROUGH- ``` License keys are provisioned automatically when you subscribe via [Polar.sh](https://polar.sh/qwady-solutions-llc/portal). Free-tier endpoints (search, areas, market, and photos) work without authentication but are tracked per IP and subject to IP-based rate limits of 10 requests per minute. The health check endpoint remains fully public. ## Rate Limits | Tier | Requests/min | Requests/month | Max perPage | |----------|-------------|----------------|-------------| | Free | 10 | 100 | 10 | | Starter | 30 | 5,000 | 50 | | Pro | 60 | 25,000 | 500 | | Business | 120 | 100,000 | 500 | Tiered API responses include the `X-RateLimit-Limit` and `X-Quota-*` headers, plus an `X-Request-Id` header (UUID v4) for request tracing and debugging. Note that 429 responses additionally carry a `Retry-After` header and an `error.retryAfter` value in the body. The health check remains fully public and does not carry quota headers. ## Data Freshness Freshness-aware JSON data responses include a `meta.dataAge` field (ISO 8601) indicating when the underlying data was last scraped, and a `meta.source` field indicating how the data was served (`cached`, `stale`, or `live`). Public cache cadence varies by dataset: rental search refreshes every 6h, sale search every 8h, listing detail sweeps every 12h, buildings daily at 03:00 UTC, and market snapshots daily at 05:00 UTC. Broadband enrichment is checked monthly, but the underlying FCC source data is published only twice a year, so most checks are a no-op; broadband fields currently cover 76.5% of eligible buildings (those with an active listing and geocodes). Thresholds behave differently on detail routes than on search: - **Property and building detail**: a paid-tier request for data older than the tier's threshold queues a background refresh, so a subsequent request returns fresher data. - **Search**: crossing the threshold only changes the label. Results are returned as-is with `meta.source: "stale"` and **no refresh is queued**. Search freshness comes solely from the scrape cadence above, so a stale search generally means a scheduled scrape was missed. The 8h value is flat across every paid tier for that reason. - **Free tier**: never triggers a refresh on any route. | Tier | Search Threshold (label only) | Listing Threshold | Building Threshold | |----------|-------------------------------|-------------------|--------------------| | Starter | 8h | 30min | 6h | | Pro | 8h | 15min | 3h | | Business | 8h | 10min | 2h | ## Photo URLs Listing and building responses include photo keys (32-character hex hashes). Use the Borough proxy for first-party image URLs: ``` https://borough.qwady.app/v1/photos/{key} ``` Supported sizes: ``` large_800_400 (default), medium_500_250 ``` version: 1.0.0 contact: name: Qwady Solutions LLC url: https://borough.qwady.app email: api@qwady.com license: name: Proprietary url: https://borough.qwady.app/terms servers: - url: https://borough.qwady.app/v1 description: Production security: - BearerAuth: [] tags: - name: Search description: Search rental and sale listings with filters - name: Property description: Individual listing details and price history - name: Building description: Building information, amenities, and active listings - name: Areas description: Neighborhoods, boroughs, and geographic boundaries - name: Market description: Market snapshots, trends, and area comparisons - name: Webhooks description: Webhook subscriptions for listing change notifications - name: Watchers description: >- Persistent watchers that poll listings, buildings, and searches on a schedule - name: Streaming description: Server-Sent Events for live data and watcher changes - name: Utility description: Health checks and internal endpoints paths: /areas: get: tags: - Areas summary: List areas and neighborhoods description: > Returns the area hierarchy: 349 areas across NYC and Northern New Jersey, of which 316 are NYC neighborhoods and sub-areas and 5 are boroughs. Optionally filter by level or parent area. This route is paginated: `perPage` defaults to 10 (and is capped at 10 on the Free tier), so a single unfiltered call returns 10 of 349 rows. Read `meta.total` and page through, or raise `perPage` on a paid tier. **Tier:** Free+ operationId: listAreas parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/perPage' - name: level in: query description: >- Area hierarchy level (0 = NYC top container, 1 = borough, 2-5 = neighborhood; Manhattan neighborhoods are level 3, outer-borough neighborhoods level 2). schema: type: integer minimum: 0 maximum: 5 - name: parentId in: query description: >- Filter by parent area ID (100=Manhattan, 200=Bronx, 300=Brooklyn, 400=Queens, 500=Staten Island) schema: type: integer - name: q in: query description: >- Case-insensitive area name or slug lookup. Exact name matches are returned first, followed by broader suggestions. schema: type: string minLength: 1 - name: include in: query description: Include optional boundary data in each area record. schema: type: string enum: - boundary responses: '200': description: List of areas content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Area' meta: $ref: '#/components/schemas/PaginatedMeta' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalError' security: [] components: parameters: page: name: page in: query description: Page number (1-indexed) schema: type: integer minimum: 1 default: 1 perPage: name: perPage in: query description: >- Results per page. Maximum depends on tier: Free=10, Starter=50, Pro/Business=500. schema: type: integer minimum: 1 maximum: 500 default: 10 schemas: Area: type: object properties: id: type: integer name: type: string level: type: integer minimum: 0 maximum: 5 description: >- Area hierarchy level (0 = NYC top container, 1 = borough, 2-5 = neighborhood; Manhattan neighborhoods are level 3, outer-borough neighborhoods level 2). parentId: type: - integer - 'null' slug: type: - string - 'null' encodedBoundary: type: - string - 'null' PaginatedMeta: allOf: - $ref: '#/components/schemas/Meta' - type: object properties: total: type: integer page: type: integer perPage: type: integer links: $ref: '#/components/schemas/PaginationLinks' warnings: type: array items: type: string description: >- Data coverage or behavior caveats for requested filters. Present when one or more of the following are used, since each depends on data that is detail-only or feed-estimated and so may under-return against the full population: `fiberOnly`/`minDownloadMbps`, `minTransitScore`, `has3dTour=true`, `noFee=true`, `hasOpenHouse=true`, `minSqft`/`maxSqft`, `amenities`, and the `listedAt`-derived filters (`minDaysOnMarket`, `maxDaysOnMarket`, `listedAfter`, `listedBefore`, `sort=LISTED_AT`). See the [data freshness guide](/borough/guides/data-freshness) and [filtering guide](/borough/guides/filtering). Meta: type: object properties: dataAge: type: - string - 'null' format: date-time description: When the underlying data was last refreshed (ISO 8601) source: type: string enum: - cached - stale - live description: > How this data was served: - `cached`: From D1 database, within the tier's freshness threshold. - `stale`: From D1 but older than the tier's freshness threshold. On property and building detail this also queues a background refresh for paid tiers. On **search** it is a label only; the results are returned as-is and no refresh is queued, on any tier. - `live`: Fetched live from source (Business/Internal tiers on property and building detail endpoints). freshnessThreshold: type: - integer - 'null' description: >- Freshness threshold in minutes for the current tier. Emitted only on property and building detail, where paid-tier data older than this queues a background refresh. Search applies a threshold internally to decide whether `source` reads `cached` or `stale`, but does not emit this field; do not expect it on a search response. Also omitted on routes that do not evaluate a threshold at all. refreshTriggered: type: - boolean - 'null' description: >- Whether a background refresh was queued for this request. Only property and building detail routes queue refreshes; search never does, so this is never `true` on a search response. detailScraped: type: boolean description: >- Present on `/property/{id}/history`, `/property/{id}/fees`, and `/property/{id}/open-houses`. Disambiguates an empty `data` array: `false` means this listing has never been detail-scraped, so the list was never checked, not "checked, and there's nothing there." When `false`, `dataAge` is also `null` for the same reason. See the [data freshness guide](/borough/guides/data-freshness). PaginationLinks: type: object description: Pagination navigation links properties: self: type: string format: uri first: type: string format: uri last: type: string format: uri prev: type: - string - 'null' format: uri next: type: - string - 'null' format: uri ErrorResponse: type: object properties: error: type: object required: - code - message - status properties: code: type: string enum: - INVALID_PARAMS - MISSING_API_KEY - INVALID_API_KEY - EXPIRED_API_KEY - TIER_RESTRICTED - QUOTA_EXCEEDED - NOT_FOUND - WEBHOOK_NOT_FOUND - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - UPSTREAM_ERROR - SERVICE_DISABLED message: type: string status: type: integer retryAfter: type: - integer - 'null' description: Seconds to wait before retrying (for 429 responses) quotaContext: type: - object - 'null' description: >- Upgrade context included on QUOTA_EXCEEDED (429) responses; null or absent otherwise. properties: currentTier: type: string currentQuota: type: integer nextTier: type: - string - 'null' nextTierQuota: type: - integer - 'null' upgradeUrl: type: string format: uri responses: BadRequest: description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INVALID_PARAMS message: Parameter 'maxPrice' must be a positive integer. status: 400 InternalError: description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL_ERROR message: >- An unexpected error occurred. Please retry or contact support with the X-Request-Id. status: 500 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: BOROUGH- description: 'Polar.sh license key. Format: `BOROUGH-`' ````