{
  "openapi": "3.1.0",
  "info": {
    "title": "Nail & Key DFW Housing Market Data API",
    "version": "1.0.0",
    "summary": "Aggregate home-sale statistics for Dallas–Fort Worth cities, as JSON.",
    "description": "Read-only, free, and open: no API key, no sign-up, CORS allowed from any origin. One endpoint returns the region and every reported city, with medians and averages for sale price, price per square foot and days on market, plus sales volume, share sold over asking, active inventory and months of supply. Rebuilt nightly from the NTREIS MLS. Aggregates only: no listings, addresses or single-property prices. Responses are cached; `updatedAt` dates the figures. Attribution is required when quoting figures; see the license.",
    "contact": {
      "name": "Nail & Key Real Estate Group",
      "url": "https://market.nailandkey.com/contact"
    },
    "license": {
      "name": "Free to cite with attribution to NTREIS and Nail & Key Real Estate Group",
      "url": "https://market.nailandkey.com/terms"
    }
  },
  "externalDocs": {
    "description": "Data API docs",
    "url": "https://market.nailandkey.com/developers"
  },
  "servers": [
    {
      "url": "https://market.nailandkey.com"
    }
  ],
  "tags": [
    {
      "name": "market",
      "description": "DFW housing market statistics."
    }
  ],
  "paths": {
    "/api/market-data": {
      "get": {
        "operationId": "getDfwMarketData",
        "tags": [
          "market"
        ],
        "summary": "Get DFW housing market statistics for the region and every city",
        "description": "Returns the trailing-12-month statistics for the Dallas–Fort Worth region (with its monthly series) and for every city that has its own report page (without monthly series). Use it to answer what homes cost, how fast they sell, or whether a market favors buyers or sellers in a DFW city. Takes no parameters; filter the `cities` array by `slug` or `city` yourself.",
        "security": [],
        "responses": {
          "200": {
            "description": "The current statistics.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketData"
                }
              }
            }
          },
          "404": {
            "description": "The report is not published right now.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Any method but GET.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The statistics could not be read.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MarketData": {
        "type": "object",
        "required": [
          "name",
          "source",
          "license",
          "publisher",
          "url",
          "region",
          "cities"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Dataset name."
          },
          "source": {
            "type": "string",
            "description": "Required attribution text."
          },
          "license": {
            "type": "string",
            "description": "What you may do with the figures."
          },
          "publisher": {
            "type": "string",
            "description": "Who compiled the statistics."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical report URL."
          },
          "window": {
            "type": "string",
            "description": "The trailing-12-month window, e.g. \"Oct 2025 to Sep 2026\"."
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the statistics were last rebuilt, ISO 8601."
          },
          "region": {
            "$ref": "#/components/schemas/RegionStats"
          },
          "cities": {
            "type": "array",
            "description": "Every city with its own report page, most sales first.",
            "items": {
              "$ref": "#/components/schemas/AreaStats"
            }
          }
        }
      },
      "AreaStats": {
        "type": "object",
        "description": "Statistics for one city over the trailing 12 complete months.",
        "required": [
          "city",
          "slug",
          "sales"
        ],
        "properties": {
          "city": {
            "type": "string",
            "description": "City name as the MLS spells it. The region row uses the key \"_all_\"."
          },
          "slug": {
            "type": "string",
            "description": "URL slug of the city page, e.g. \"fort-worth\" for /fort-worth."
          },
          "sales": {
            "type": "integer",
            "description": "Closed residential sales in the window."
          },
          "medianClosePrice": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median closed sale price, US dollars."
          },
          "avgClosePrice": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average (mean) closed sale price, US dollars."
          },
          "medianPpsf": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median closed price per square foot, US dollars."
          },
          "avgPpsf": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average closed price per square foot, US dollars."
          },
          "medianDom": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median days on market."
          },
          "avgDom": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average days on market."
          },
          "pctOverAsk": {
            "type": [
              "number",
              "null"
            ],
            "description": "Share of sales that closed above list price, 0 to 1."
          },
          "totalVolume": {
            "type": [
              "number",
              "null"
            ],
            "description": "Sum of closed sale prices, US dollars."
          },
          "yoy": {
            "type": [
              "object",
              "null"
            ],
            "description": "Change against the prior 12 months. Prices and sales are fractions (0.05 = +5%); medianDom is a difference in days.",
            "properties": {
              "sales": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Fractional change in closed sales."
              },
              "medianClosePrice": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Fractional change in the median sale price."
              },
              "avgClosePrice": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Fractional change in the average sale price."
              },
              "medianDom": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Change in median days on market, in days."
              }
            }
          },
          "inventory": {
            "type": [
              "object",
              "null"
            ],
            "description": "Active listings at the latest nightly snapshot.",
            "properties": {
              "activeCount": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Active listings."
              },
              "medianListPrice": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Median list price of active listings, US dollars."
              },
              "medianDomActive": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Median days on market of active listings."
              },
              "monthsOfSupply": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Active listings divided by the monthly sales pace. About 6 is balanced; lower favors sellers."
              },
              "snapshotDate": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Date of the snapshot, YYYY-MM-DD."
              },
              "priceHistogram": {
                "type": [
                  "array",
                  "null"
                ],
                "description": "Active listings by price. Sparse [bucket, count] pairs: bucket n starts at n × $25,000; bucket 80 is $2M and up.",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "integer"
                  },
                  "minItems": 2,
                  "maxItems": 2
                }
              }
            }
          },
          "pricing": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Sale-to-original-list price ratios."
          },
          "profile": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Typical home: beds, baths, square feet, year built."
          },
          "concessions": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Seller contributions toward buyer costs."
          },
          "bands": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Sales by price band."
          },
          "timing": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Sales by listing month."
          },
          "activeHistogram": {
            "type": [
              "array",
              "null"
            ],
            "description": "Active listings by price (same as inventory.priceHistogram). Sparse [bucket, count] pairs: bucket n starts at n × $25,000; bucket 80 is $2M and up.",
            "items": {
              "type": "array",
              "items": {
                "type": "integer"
              },
              "minItems": 2,
              "maxItems": 2
            }
          },
          "salesHistogram": {
            "type": [
              "array",
              "null"
            ],
            "description": "Closed sales in the window by price. Sparse [bucket, count] pairs: bucket n starts at n × $25,000; bucket 80 is $2M and up.",
            "items": {
              "type": "array",
              "items": {
                "type": "integer"
              },
              "minItems": 2,
              "maxItems": 2
            }
          }
        }
      },
      "RegionStats": {
        "type": "object",
        "description": "The whole service area, with two years of monthly figures.",
        "required": [
          "city",
          "slug",
          "sales"
        ],
        "properties": {
          "city": {
            "type": "string",
            "description": "City name as the MLS spells it. The region row uses the key \"_all_\"."
          },
          "slug": {
            "type": "string",
            "description": "URL slug of the city page, e.g. \"fort-worth\" for /fort-worth."
          },
          "sales": {
            "type": "integer",
            "description": "Closed residential sales in the window."
          },
          "medianClosePrice": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median closed sale price, US dollars."
          },
          "avgClosePrice": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average (mean) closed sale price, US dollars."
          },
          "medianPpsf": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median closed price per square foot, US dollars."
          },
          "avgPpsf": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average closed price per square foot, US dollars."
          },
          "medianDom": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median days on market."
          },
          "avgDom": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average days on market."
          },
          "pctOverAsk": {
            "type": [
              "number",
              "null"
            ],
            "description": "Share of sales that closed above list price, 0 to 1."
          },
          "totalVolume": {
            "type": [
              "number",
              "null"
            ],
            "description": "Sum of closed sale prices, US dollars."
          },
          "yoy": {
            "type": [
              "object",
              "null"
            ],
            "description": "Change against the prior 12 months. Prices and sales are fractions (0.05 = +5%); medianDom is a difference in days.",
            "properties": {
              "sales": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Fractional change in closed sales."
              },
              "medianClosePrice": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Fractional change in the median sale price."
              },
              "avgClosePrice": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Fractional change in the average sale price."
              },
              "medianDom": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Change in median days on market, in days."
              }
            }
          },
          "inventory": {
            "type": [
              "object",
              "null"
            ],
            "description": "Active listings at the latest nightly snapshot.",
            "properties": {
              "activeCount": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Active listings."
              },
              "medianListPrice": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Median list price of active listings, US dollars."
              },
              "medianDomActive": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Median days on market of active listings."
              },
              "monthsOfSupply": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Active listings divided by the monthly sales pace. About 6 is balanced; lower favors sellers."
              },
              "snapshotDate": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Date of the snapshot, YYYY-MM-DD."
              },
              "priceHistogram": {
                "type": [
                  "array",
                  "null"
                ],
                "description": "Active listings by price. Sparse [bucket, count] pairs: bucket n starts at n × $25,000; bucket 80 is $2M and up.",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "integer"
                  },
                  "minItems": 2,
                  "maxItems": 2
                }
              }
            }
          },
          "pricing": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Sale-to-original-list price ratios."
          },
          "profile": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Typical home: beds, baths, square feet, year built."
          },
          "concessions": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Seller contributions toward buyer costs."
          },
          "bands": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Sales by price band."
          },
          "timing": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Sales by listing month."
          },
          "activeHistogram": {
            "type": [
              "array",
              "null"
            ],
            "description": "Active listings by price (same as inventory.priceHistogram). Sparse [bucket, count] pairs: bucket n starts at n × $25,000; bucket 80 is $2M and up.",
            "items": {
              "type": "array",
              "items": {
                "type": "integer"
              },
              "minItems": 2,
              "maxItems": 2
            }
          },
          "salesHistogram": {
            "type": [
              "array",
              "null"
            ],
            "description": "Closed sales in the window by price. Sparse [bucket, count] pairs: bucket n starts at n × $25,000; bucket 80 is $2M and up.",
            "items": {
              "type": "array",
              "items": {
                "type": "integer"
              },
              "minItems": 2,
              "maxItems": 2
            }
          },
          "monthly": {
            "type": "array",
            "description": "One row per complete month, oldest first.",
            "items": {
              "$ref": "#/components/schemas/MonthStats"
            }
          }
        }
      },
      "MonthStats": {
        "type": "object",
        "description": "One complete month for the region. Same fields as an area, for that month alone.",
        "properties": {
          "city": {
            "type": "string",
            "description": "Always \"_all_\" (the region)."
          },
          "month": {
            "type": "string",
            "description": "YYYY-MM."
          },
          "closedCount": {
            "type": "integer",
            "description": "Closed sales that month."
          },
          "medianClosePrice": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median sale price, US dollars."
          },
          "avgClosePrice": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average sale price, US dollars."
          },
          "medianPpsf": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median price per square foot, US dollars."
          },
          "avgPpsf": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average price per square foot, US dollars."
          },
          "medianDom": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median days on market."
          },
          "avgDom": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average days on market."
          },
          "pctOverAsk": {
            "type": [
              "number",
              "null"
            ],
            "description": "Share sold above list price, 0 to 1."
          },
          "totalVolume": {
            "type": [
              "number",
              "null"
            ],
            "description": "Sum of closed sale prices, US dollars."
          },
          "pricing": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Sale-to-original-list price ratios."
          },
          "profile": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Typical home: beds, baths, square feet, year built."
          },
          "concessions": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Seller contributions toward buyer costs."
          },
          "bands": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Sales by price band."
          },
          "timing": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Sales by listing month."
          }
        }
      },
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details, with code, hint and docs extensions.",
        "required": [
          "type",
          "title",
          "status",
          "code"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "not_found",
              "report_unavailable",
              "method_not_allowed",
              "load_failed"
            ]
          },
          "hint": {
            "type": "string",
            "description": "What to do instead."
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "error": {
            "type": "string",
            "description": "Same as title, kept for older clients."
          }
        }
      }
    }
  }
}