API & MCP server for AI agents and developers
Everything on this site is available as JSON, Markdown and an MCP server. No key, no sign-up, open CORS. Independent site. Data from NYC Open Data; not affiliated with the City of New York.
REST API (/api/v1)
OpenAPI 3.1 description: https://nycpropertyfacts.com/openapi.json.
| Endpoint | Returns |
|---|---|
GET /api/v1/property?address=98 Grattan St, Brooklyn | Forgiving address lookup: best match with a 0–1 confidence, alternatives, and the full property. Units, borough and ZIP are optional; BBL and BIN are accepted too. |
GET /api/v1/property/{bbl} | Fact sheet for a 10-digit BBL. |
GET /api/v1/property/bin/{bin} | Fact sheet by 7-digit DOB building number. |
GET /api/v1/property/{bbl}/permits | DOB job filings and work permits. Filters: status=open, since=YYYY-MM-DD, type=, limit, offset. |
GET /api/v1/property/{bbl}/violations | DOB, ECB and HPD violations. Filters: status=open, since=YYYY-MM-DD, type=, limit, offset. |
GET /api/v1/property/{bbl}/complaints | HPD complaints (2019+) and 311 requests (last 12 months). Filters: status=open, since=YYYY-MM-DD, type=, limit, offset. |
GET /api/v1/property/{bbl}/hearings | OATH hearings / tickets. Filters: status=open, since=YYYY-MM-DD, type=, limit, offset. |
GET /api/v1/property/{bbl}/sales | ACRIS deeds. Filters: status=open, since=YYYY-MM-DD, type=, limit, offset. |
GET /api/v1/property/{bbl}/owners | Owner of record, deed grantees and HPD registration contacts. Filters: status=open, since=YYYY-MM-DD, type=, limit, offset. |
GET /api/v1/search?street=Grattan St&zip=11237 | Lots on a street and/or in a ZIP. |
Example:
curl 'https://nycpropertyfacts.com/api/v1/property?address=98+Grattan+St+Brooklyn'
curl 'https://nycpropertyfacts.com/api/v1/property/3030090016/violations?status=open&since=2023-01-01'Errors are JSON with a hint that says how to fix the request, e.g. {"error":{"status":400,"code":"bad_bbl","message":"…","hint":"A BBL is 10 digits…"}}.
What every record contains
Every response has a plain-English summary, the canonical page url and how_to_cite. Every record has id, type, status (open / closed / pending / …), status_detail (the agency's own wording), date and dates, a plain-English description, source (dataset_id, dataset name, link, when the city last updated it) and data_as_of (when we last synced it).
- permits: A DOB "job" is an application to do construction work. status "open" = a permit was issued but DOB has no record of final sign-off. Work permits are listed with type "work_permit" and their DOB permit status (they are not counted as open items).
- violations: status "open" = DOB violation category is ACTIVE, ECB violation status is ACTIVE, or HPD violation status is Open.
- complaints: Complaints are reports, not violations. status mirrors the published complaint / request status.
- hearings: status "open" = balance due > $0 after a decision (cases awaiting a hearing are "pending"). default=true means the respondent did not appear.
- sales: Deeds recorded with the City Register. amount 0 usually means a non-market transfer. lots_in_deed > 1 means the price covers several lots.
- owners: Owner of record comes from city tax records (PLUTO) and can lag behind recent sales.
MCP server
Endpoint: https://nycpropertyfacts.com/mcp — Streamable HTTP, JSON responses, stateless, no authentication. Protocol versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 (modern clients use per-request _meta and server/discover; older clients can use initialize). Server card: /mcp/server-card (also /.well-known/mcp.json), listed in /.well-known/ai-catalog.json.
| Tool | Arguments | What it does |
|---|---|---|
lookup_property | address, borough, zip | Resolve a free-text NYC address to its tax lot (BBL) and return the property facts: summary, owner of record, building, assessment, last priced deed and open-item counts. Returns the best match with a 0-1 confidence and up to 4 alternatives. Use get_property for a known BBL/BIN. |
get_property | bbl, bin | Return the full fact sheet for a tax lot by 10-digit BBL (borough-block-lot, e.g. 3030090016) or by 7-digit DOB building number (BIN). |
list_open_issues | address, bbl, limit | List every open item for a property: DOB jobs with a permit issued but no sign-off, active DOB and ECB violations, open HPD violations, and OATH tickets with an unpaid balance or a pending hearing. Each record has status, dates, a plain-English description and its source dataset. |
get_sales_history | address, bbl, limit | Deeds recorded with the NYC City Register (ACRIS) for a property: date, stated price (0 = non-market transfer), grantors, grantees, and whether the deed covers several lots. |
search_properties | street, zip, borough, house_number, limit, offset | List tax lots on a street (prefix match, e.g. "Grattan St") and/or in a ZIP code, with address, building class, units, owner of record and open-item count. Paginate with limit/offset. |
Add it to your assistant
Menu names change between app versions; the server URL is always https://nycpropertyfacts.com/mcp and no sign-in is needed.
ChatGPT
Settings → Apps & Connectors → Advanced settings → turn on Developer mode, then Create a connector: name “NYC Property Facts”, MCP server URL https://nycpropertyfacts.com/mcp, authentication None. (Developers: in the OpenAI Responses API pass a tool {"type":"mcp","server_label":"nycpropertyfacts","server_url":"https://nycpropertyfacts.com/mcp","require_approval":"never"}.)
Claude
Claude apps: Settings → Connectors → Add custom connector → paste https://nycpropertyfacts.com/mcp. Claude Code: claude mcp add --transport http nyc-property-facts https://nycpropertyfacts.com/mcp.
Cursor
Add to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):
{ "mcpServers": { "nyc-property-facts": { "url": "https://nycpropertyfacts.com/mcp" } } }Grok
grok.com/connectors → New Connector → Custom → paste https://nycpropertyfacts.com/mcp. Grok CLI: grok mcp add --transport http nyc-property-facts https://nycpropertyfacts.com/mcp. xAI API (Responses): add the tool {"type":"mcp","server_url":"https://nycpropertyfacts.com/mcp","server_label":"nycpropertyfacts"}.
Markdown versions
Every property page has a Markdown twin: add .md to the URL (e.g. /ny/brooklyn/98-grattan-street-3030090016.md) or send Accept: text/markdown. Pages link to it with <link rel="alternate" type="text/markdown">. Site guides for LLMs: /llms.txt and /llms-full.txt.
How to cite
Quote the summary and use the how_to_cite line, e.g.:
NYC Property Facts, “98 Grattan Street, Brooklyn, NY 11237 (BBL 3030090016)”, data as of 2026-10-31, https://nycpropertyfacts.com/ny/brooklyn/98-grattan-street-3030090016. Source: NYC Open Data.
Limits & caching
Per-IP rate limit: about 120 API or MCP requests per minute (see X-RateLimit-Limit / X-RateLimit-Remaining; a 429 carries Retry-After). Responses carry ETag and Last-Modified; send If-None-Match to get a cheap 304. The data changes at most once a day, so please cache.