{
  "openapi": "3.1.0",
  "info": {
    "title": "PriceDNA API",
    "version": "1.0.0",
    "summary": "Property analysis, geocoding and rent, as JSON.",
    "description": "Three APIs, one key. The Property API returns the report people see in the app. The Geocoding API places addresses and points, with the census tract and flood risk when you ask. The Rent API returns typical rent and its range by bedroom count, with HUD’s fair market rent. Money is whole dollars, rates are percent numbers (5.2 means 5.2%), and nothing numeric arrives as a string. v1 only changes additively.",
    "contact": {
      "url": "https://www.pricedna.co/api/"
    }
  },
  "servers": [
    {
      "url": "https://api.pricedna.co"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "tags": [
    {
      "name": "Property",
      "description": "Property report, as JSON: the price your goal can support, and every section behind it.",
      "x-page": "/api/property/"
    },
    {
      "name": "Geocoding",
      "description": "Addresses to points and points to the nearest address, with the census tract and flood risk when you ask.",
      "x-page": "/api/geocoding/"
    },
    {
      "name": "Rent",
      "description": "Typical rent and its range by bedroom count, with yearly growth, for any US place.",
      "x-page": "/api/rent/"
    }
  ],
  "paths": {
    "/v1/property": {
      "post": {
        "operationId": "analyze",
        "summary": "Analyze a rental property against your goal",
        "description": "Analyzes a rental property to buy, from 1 to 500 units, against your goal. Only `address` and `number_of_units` are required. All other parameters are optional and default to location-calibrated market values when omitted.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Send the same key to retry safely. Within 24 hours, a repeat returns the first answer, marked `Idempotent-Replayed: true`, with no second charge.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255,
              "pattern": "^[\\x21-\\x7E]+$"
            },
            "example": "6f1c2b0e-concord-1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalyzeRequest"
              },
              "examples": {
                "quick_start": {
                  "summary": "The Concord demo report",
                  "value": {
                    "address": "123 Union St S, Concord, NC 28025",
                    "number_of_units": 5,
                    "asking_price": 849000,
                    "monthly_rent": 1524,
                    "goal": {
                      "metric": "cash_velocity",
                      "target": 200
                    },
                    "mortgage_interest_rate": 7,
                    "vacancy_rate": 5
                  }
                },
                "minimal": {
                  "summary": "Required fields only",
                  "value": {
                    "address": "123 Union St S, Concord, NC 28025",
                    "number_of_units": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Report"
                },
                "example": {
                  "report_id": "93a2715c795b47b9acc2cf50dd2a7b76",
                  "created_at": "2026-10-08T13:11:56Z",
                  "links": {
                    "report": "https://www.pricedna.co/reports/93a2715c795b47b9acc2cf50dd2a7b76"
                  },
                  "property": {
                    "address": "123 Union St S, Concord, NC 28025",
                    "lat": 35.4,
                    "lng": -80.58,
                    "asking_price": 849000,
                    "units": 5,
                    "flood_zone": false,
                    "coastal_flood_zone": false
                  },
                  "goal": {
                    "metric": "cash_velocity",
                    "target": 200,
                    "achieved": 200
                  },
                  "estimate": {
                    "price": 786000,
                    "gap_percent": 8.0,
                    "summary": "The asking price is 8.0% above your goal-convergent price.",
                    "tone": "neutral",
                    "market_value": {
                      "method": "income",
                      "value": 812000,
                      "net_operating_income": 53600,
                      "market_cap_rate": 6.6,
                      "low": null,
                      "high": null,
                      "year": null,
                      "level": null,
                      "source": "PriceDNA income value"
                    }
                  },
                  "projections": {
                    "cash_invested": 230000,
                    "expected": {
                      "years": [
                        {
                          "years": 3,
                          "appreciation": 117000,
                          "cash_flow": 43000,
                          "loan_paydown": 19300,
                          "upfront_costs": 33700,
                          "net_gain": 145600,
                          "roi": 63,
                          "equity_multiple": 1.63
                        }
                      ]
                    },
                    "downturn": {
                      "replays": {
                        "area": "Cabarrus County",
                        "name": "the housing crisis",
                        "start_year": 2008,
                        "end_year": 2013,
                        "price_drop": 17,
                        "rents_replayed": true
                      },
                      "years": [
                        {
                          "years": 3,
                          "net_gain": -69600,
                          "roi": -30,
                          "equity_multiple": 0.7
                        }
                      ]
                    },
                    "market_phase": {
                      "phase": "steady",
                      "scope": null,
                      "years_in_phase": 1,
                      "typical_years_left": 3,
                      "usually_followed_by": "slowed",
                      "area": "Cabarrus County",
                      "summary": "Cabarrus County’s market is growing steadily: prices are near their peak and rising at a typical pace. In past markets, steady stretches like this usually lasted about 3 more years, and most often turned into a slow stretch."
                    }
                  },
                  "location": {
                    "score": 81,
                    "label": "very good",
                    "factors": [
                      {
                        "name": "economic_strength",
                        "label": "Economic Strength",
                        "weight": 28,
                        "rating": "very good"
                      },
                      {
                        "name": "rental_market",
                        "label": "Rental Market",
                        "weight": 22,
                        "rating": "good"
                      },
                      {
                        "name": "housing_market",
                        "label": "Housing Market",
                        "weight": 18,
                        "rating": "good"
                      },
                      {
                        "name": "climate_resilience",
                        "label": "Climate Resilience",
                        "weight": 12,
                        "rating": "good"
                      },
                      {
                        "name": "safety",
                        "label": "Safety",
                        "weight": 10,
                        "rating": "good"
                      },
                      {
                        "name": "urbanization",
                        "label": "Urbanization",
                        "weight": 10,
                        "rating": "good"
                      }
                    ]
                  },
                  "neighborhood": [
                    {
                      "radius_mi": 1,
                      "population": 4190,
                      "households": 1466,
                      "renter_occupied": 14.53,
                      "renter_age": 37.21,
                      "college_educated": 53.62,
                      "vacant": 12.32
                    }
                  ],
                  "nearby_influences": [
                    {
                      "category": "rail_tracks",
                      "label": "Rail tracks",
                      "radius_mi": 1,
                      "found": [
                        {
                          "name": "NS",
                          "distance_mi": 0.84
                        },
                        {
                          "name": "NS",
                          "distance_mi": 0.85
                        }
                      ]
                    },
                    {
                      "category": "airports",
                      "label": "Airports",
                      "radius_mi": 4,
                      "found": []
                    }
                  ],
                  "market_pulse": [
                    {
                      "title": "100-year-old church in Concord transformed into affordable housing",
                      "source": "wsoctv.com",
                      "date": "2026-07-14",
                      "url": "https://www.wsoctv.com/"
                    }
                  ],
                  "deal_metrics": {
                    "cash_velocity": 200,
                    "cash_on_cash_return": 5.2,
                    "dscr": 1.26,
                    "noi": 59100,
                    "operating_cap_rate": 7.5,
                    "opex_ratio": 32,
                    "mortgage_payment": 3921,
                    "total_investment": 230000,
                    "one_percent_rule": 0.85,
                    "grm": 9.8
                  },
                  "assumptions": [
                    {
                      "name": "monthly_rent",
                      "label": "Monthly rent",
                      "value": 1524,
                      "unit": "$",
                      "entered": true
                    },
                    {
                      "name": "mortgage_interest_rate",
                      "label": "Interest rate",
                      "value": 7,
                      "unit": "%",
                      "entered": true
                    },
                    {
                      "name": "vacancy_rate",
                      "label": "Vacancy",
                      "value": 5,
                      "unit": "%",
                      "entered": true
                    },
                    {
                      "name": "property_tax_rate",
                      "label": "Property tax",
                      "value": 0.78,
                      "unit": "%",
                      "entered": false
                    },
                    {
                      "name": "rent_growth",
                      "label": "Rent growth",
                      "value": "projected",
                      "model": "PriceDNA rent growth model",
                      "entered": false
                    }
                  ]
                }
              }
            },
            "headers": {
              "Idempotent-Replayed": {
                "description": "`true` when the response is a replay of an earlier request with the same `Idempotency-Key`.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Your request has invalid fields. Invalid request.",
            "x-problem-types": [
              {
                "slug": "validation-error",
                "title": "Your request has invalid fields",
                "description": "Some fields are invalid. `errors` lists each one and what is wrong with it."
              },
              {
                "slug": "invalid-request",
                "title": "Invalid request",
                "description": "The request can’t be read, for example malformed JSON or an `Idempotency-Key` that isn’t 1 to 255 visible ASCII characters."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://www.pricedna.co/api#error-validation-error",
                  "title": "Your request has invalid fields",
                  "status": 400,
                  "detail": "Your request has invalid fields",
                  "errors": [
                    {
                      "field": "number_of_units",
                      "detail": "Must be between 1 and 500."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "x-problem-types": [
              {
                "slug": "unauthorized",
                "title": "Missing or invalid API key",
                "description": "The API key is missing or not valid."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "402": {
            "description": "No new properties left.",
            "x-problem-types": [
              {
                "slug": "no-new-properties-left",
                "title": "No new properties left this cycle",
                "description": "Your plan has no new properties left this cycle. `new_properties_left`, `new_properties_per_cycle` and `resets_at` say what it includes and when it resets. Reruns of a property you have analyzed still work."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://www.pricedna.co/api#error-no-new-properties-left",
                  "title": "No new properties left this cycle",
                  "status": 402,
                  "detail": "You’ve analyzed every new property your plan includes this month.",
                  "code": "NO_NEW_PROPERTIES_LEFT",
                  "new_properties_left": 0,
                  "new_properties_per_cycle": 10,
                  "resets_at": "2026-12-01T12:00:00+00:00"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "x-problem-types": [
              {
                "slug": "forbidden",
                "title": "Forbidden",
                "description": "This key can’t make this request."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "x-problem-types": [
              {
                "slug": "not-found",
                "title": "Not found",
                "description": "The path doesn’t exist."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Request in progress.",
            "x-problem-types": [
              {
                "slug": "request-in-progress",
                "title": "Request in progress",
                "description": "A request with this `Idempotency-Key` is still running. Retry after the seconds in `Retry-After`."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 5
                }
              }
            }
          },
          "422": {
            "description": "Idempotency key reused.",
            "x-problem-types": [
              {
                "slug": "idempotency-key-reused",
                "title": "Idempotency key reused",
                "description": "This `Idempotency-Key` was already used with a different body. Send a new key."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests.",
            "x-problem-types": [
              {
                "slug": "rate-limited",
                "title": "Too many requests",
                "description": "Too many requests in a short time. Nothing is counted. Wait a moment and retry."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable.",
            "x-problem-types": [
              {
                "slug": "service-unavailable",
                "title": "Service unavailable",
                "description": "The service had a problem. Retry shortly."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "Server error.",
            "x-problem-types": [
              {
                "slug": "server-error",
                "title": "Server error",
                "description": "The service had a problem. Retry shortly."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": [
          "Property"
        ],
        "x-free-plan-includes": {
          "count": 10,
          "per": "month",
          "unit": "new properties",
          "note": "A property counts once, the first time it’s analyzed. Reruns are free."
        }
      }
    },
    "/v1/geocode": {
      "post": {
        "operationId": "geocode",
        "tags": [
          "Geocoding"
        ],
        "summary": "Addresses to points",
        "description": "Places 1 to 100 US addresses. Every row returns the base fields, plus the census tract and flood fields when asked. Every row costs its lookup point, and the enrichments only when it is placed.",
        "x-free-plan-includes": {
          "count": 2500,
          "per": "day",
          "unit": "points",
          "note": "1 point per lookup, plus 1 per enrichment (census, flood) on a row we place. A row we don’t place costs its 1 point. Rows we couldn’t finish aren’t charged. Resets at midnight Eastern time."
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Send the same key to retry safely. Within 24 hours, a repeat returns the first answer, marked `Idempotent-Replayed: true`, with no second charge.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255,
              "pattern": "^[\\x21-\\x7E]+$"
            },
            "example": "6f1c2b0e-concord-1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeocodeRequest"
              },
              "examples": {
                "quick_start": {
                  "summary": "Two addresses with both enrichments: one that places, one that doesn’t",
                  "value": {
                    "addresses": [
                      "123 Union St S, Concord, NC 28025",
                      "1 Nowhere Ln, Concord, NC 28025"
                    ],
                    "census": true,
                    "flood": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One row per address, in the order sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeocodeResponse"
                },
                "example": {
                  "results": [
                    {
                      "input": "123 Union St S, Concord, NC 28025",
                      "status": "placed",
                      "reason": null,
                      "message": null,
                      "address": "123 Union St S, Concord, NC 28025",
                      "lat": 35.408416,
                      "lng": -80.578372,
                      "accuracy": "neighbor_interpolated",
                      "state": {
                        "abbr": "NC",
                        "name": "North Carolina"
                      },
                      "county": {
                        "fips": "37025",
                        "name": "Cabarrus County"
                      },
                      "city": "Concord",
                      "township": null,
                      "zip": "28025",
                      "tract": {
                        "geoid": "37025042202",
                        "number": "422.02"
                      },
                      "tribal_land": null,
                      "flood": {
                        "zone": null,
                        "risk": "minimal",
                        "in_high_risk_zone": false,
                        "coastal_county": false,
                        "coastal_flood_risk": null
                      }
                    },
                    {
                      "input": "1 Nowhere Ln, Concord, NC 28025",
                      "status": "not_found",
                      "reason": "unknown_street",
                      "message": "We can't find this street yet. If it's new, enter a nearby address.",
                      "address": null,
                      "lat": null,
                      "lng": null,
                      "accuracy": null,
                      "state": null,
                      "county": null,
                      "city": null,
                      "township": null,
                      "zip": null,
                      "tract": null,
                      "tribal_land": null,
                      "flood": null
                    }
                  ],
                  "points_used_today": 6,
                  "points_left_today": 2494,
                  "points_per_day": 2500,
                  "points_purchased_left": 0,
                  "resets_at": "2026-11-11T00:00:00-05:00"
                }
              }
            },
            "headers": {
              "Idempotent-Replayed": {
                "description": "`true` when the response is a replay of an earlier request with the same `Idempotency-Key`.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Your request has invalid fields. Invalid request.",
            "x-problem-types": [
              {
                "slug": "validation-error",
                "title": "Your request has invalid fields",
                "description": "Some fields are invalid. `errors` lists each one and what is wrong with it."
              },
              {
                "slug": "invalid-request",
                "title": "Invalid request",
                "description": "The request can’t be read, for example malformed JSON or an `Idempotency-Key` that isn’t 1 to 255 visible ASCII characters."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://www.pricedna.co/api#error-validation-error",
                  "title": "Your request has invalid fields",
                  "status": 400,
                  "detail": "Send at most 100 addresses in one request. This one has 120.",
                  "errors": [
                    {
                      "field": "addresses",
                      "detail": "Send at most 100 addresses in one request. This one has 120."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "x-problem-types": [
              {
                "slug": "unauthorized",
                "title": "Missing or invalid API key",
                "description": "The API key is missing or not valid."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "x-problem-types": [
              {
                "slug": "forbidden",
                "title": "Forbidden",
                "description": "This key can’t make this request."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Request in progress.",
            "x-problem-types": [
              {
                "slug": "request-in-progress",
                "title": "Request in progress",
                "description": "A request with this `Idempotency-Key` is still running. Retry after the seconds in `Retry-After`."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 5
                }
              }
            }
          },
          "422": {
            "description": "Idempotency key reused.",
            "x-problem-types": [
              {
                "slug": "idempotency-key-reused",
                "title": "Idempotency key reused",
                "description": "This `Idempotency-Key` was already used with a different body. Send a new key."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests, or no points left today.",
            "x-problem-types": [
              {
                "slug": "rate-limited",
                "title": "Too many requests",
                "description": "Too many requests in a short time. Nothing is counted. Wait a moment and retry."
              },
              {
                "slug": "no-points-left-today",
                "title": "No points left today",
                "description": "The request needs more points than you have left today. Nothing is charged. Send fewer rows or fewer enrichments, or wait until midnight Eastern time; `points_left` and `points_needed` say how many."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://www.pricedna.co/api#error-no-points-left-today",
                  "title": "No points left today",
                  "status": 429,
                  "detail": "This request needs 300 points and you have 40 points left today. They reset at midnight Eastern time.",
                  "code": "DAILY_POINTS_USED",
                  "points_left": 40,
                  "points_needed": 300,
                  "resets_at": "2026-11-11T00:00:00-05:00",
                  "points_per_day": 2500,
                  "points_purchased_left": 0
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds until your points reset.",
                "schema": {
                  "type": "integer",
                  "example": 18000
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable.",
            "x-problem-types": [
              {
                "slug": "service-unavailable",
                "title": "Service unavailable",
                "description": "The service had a problem. Retry shortly."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "Server error.",
            "x-problem-types": [
              {
                "slug": "server-error",
                "title": "Server error",
                "description": "The service had a problem. Retry shortly."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/reverse": {
      "post": {
        "operationId": "reverseGeocode",
        "tags": [
          "Geocoding"
        ],
        "summary": "Points to the nearest address, with every field",
        "description": "Describes 1 to 100 points in the United States, with the nearest address within 100 meters. Every row costs its lookup point, and the enrichments only when it is placed.",
        "x-free-plan-includes": {
          "count": 2500,
          "per": "day",
          "unit": "points",
          "note": "1 point per lookup, plus 1 per enrichment (census, flood) on a row we place. A row we don’t place costs its 1 point. Rows we couldn’t finish aren’t charged. Resets at midnight Eastern time."
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Send the same key to retry safely. Within 24 hours, a repeat returns the first answer, marked `Idempotent-Replayed: true`, with no second charge.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255,
              "pattern": "^[\\x21-\\x7E]+$"
            },
            "example": "6f1c2b0e-concord-1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReverseRequest"
              },
              "examples": {
                "quick_start": {
                  "summary": "One point",
                  "value": {
                    "points": [
                      {
                        "lat": 35.408416,
                        "lng": -80.578372
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One row per point, in the order sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReverseResponse"
                },
                "example": {
                  "results": [
                    {
                      "input": {
                        "lat": 35.408416,
                        "lng": -80.578372
                      },
                      "status": "placed",
                      "reason": null,
                      "message": null,
                      "address": null,
                      "lat": 35.408416,
                      "lng": -80.578372,
                      "accuracy": null,
                      "state": {
                        "abbr": "NC",
                        "name": "North Carolina"
                      },
                      "county": {
                        "fips": "37025",
                        "name": "Cabarrus County"
                      },
                      "city": "Concord",
                      "township": null,
                      "zip": "28025",
                      "tract": null,
                      "tribal_land": null,
                      "flood": null,
                      "nearest_address": {
                        "address": "133 Union St S, Concord, NC 28025",
                        "meters": 0.0
                      },
                      "nearest_address_unavailable": false
                    }
                  ],
                  "points_used_today": 1,
                  "points_left_today": 2499,
                  "points_per_day": 2500,
                  "points_purchased_left": 0,
                  "resets_at": "2026-11-11T00:00:00-05:00"
                }
              }
            },
            "headers": {
              "Idempotent-Replayed": {
                "description": "`true` when the response is a replay of an earlier request with the same `Idempotency-Key`.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Your request has invalid fields. Invalid request.",
            "x-problem-types": [
              {
                "slug": "validation-error",
                "title": "Your request has invalid fields",
                "description": "Some fields are invalid. `errors` lists each one and what is wrong with it."
              },
              {
                "slug": "invalid-request",
                "title": "Invalid request",
                "description": "The request can’t be read, for example malformed JSON or an `Idempotency-Key` that isn’t 1 to 255 visible ASCII characters."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://www.pricedna.co/api#error-validation-error",
                  "title": "Your request has invalid fields",
                  "status": 400,
                  "detail": "Send at most 100 points in one request. This one has 120.",
                  "errors": [
                    {
                      "field": "points",
                      "detail": "Send at most 100 points in one request. This one has 120."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "x-problem-types": [
              {
                "slug": "unauthorized",
                "title": "Missing or invalid API key",
                "description": "The API key is missing or not valid."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "x-problem-types": [
              {
                "slug": "forbidden",
                "title": "Forbidden",
                "description": "This key can’t make this request."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Request in progress.",
            "x-problem-types": [
              {
                "slug": "request-in-progress",
                "title": "Request in progress",
                "description": "A request with this `Idempotency-Key` is still running. Retry after the seconds in `Retry-After`."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 5
                }
              }
            }
          },
          "422": {
            "description": "Idempotency key reused.",
            "x-problem-types": [
              {
                "slug": "idempotency-key-reused",
                "title": "Idempotency key reused",
                "description": "This `Idempotency-Key` was already used with a different body. Send a new key."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests, or no points left today.",
            "x-problem-types": [
              {
                "slug": "rate-limited",
                "title": "Too many requests",
                "description": "Too many requests in a short time. Nothing is counted. Wait a moment and retry."
              },
              {
                "slug": "no-points-left-today",
                "title": "No points left today",
                "description": "The request needs more points than you have left today. Nothing is charged. Send fewer rows or fewer enrichments, or wait until midnight Eastern time; `points_left` and `points_needed` say how many."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://www.pricedna.co/api#error-no-points-left-today",
                  "title": "No points left today",
                  "status": 429,
                  "detail": "This request needs 300 points and you have 40 points left today. They reset at midnight Eastern time.",
                  "code": "DAILY_POINTS_USED",
                  "points_left": 40,
                  "points_needed": 300,
                  "resets_at": "2026-11-11T00:00:00-05:00",
                  "points_per_day": 2500,
                  "points_purchased_left": 0
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds until your points reset.",
                "schema": {
                  "type": "integer",
                  "example": 18000
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable.",
            "x-problem-types": [
              {
                "slug": "service-unavailable",
                "title": "Service unavailable",
                "description": "The service had a problem. Retry shortly."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "Server error.",
            "x-problem-types": [
              {
                "slug": "server-error",
                "title": "Server error",
                "description": "The service had a problem. Retry shortly."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/rent": {
      "post": {
        "operationId": "rent",
        "tags": [
          "Rent"
        ],
        "summary": "Typical rent and its range, by bedroom count",
        "description": "Answers 1 to 100 places with the typical rent and range for studios to 4 bedrooms, yearly rent growth, and HUD’s fair market rent with its fiscal year and ZIP codes. Every row counts as one rent check, found or not.",
        "x-free-plan-includes": {
          "count": 100,
          "per": "month",
          "unit": "rent checks",
          "note": "1 rent check per place you send, found or not. Places we couldn’t finish don’t count. Resets on the 1st."
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Send the same key to retry safely. Within 24 hours, a repeat returns the first answer, marked `Idempotent-Replayed: true`, with no second charge.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255,
              "pattern": "^[\\x21-\\x7E]+$"
            },
            "example": "6f1c2b0e-concord-1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RentRequest"
              },
              "examples": {
                "quick_start": {
                  "summary": "One census tract",
                  "value": {
                    "places": [
                      {
                        "tract": "37025042202"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One row per place, in the order sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RentResponse"
                },
                "example": {
                  "results": [
                    {
                      "input": {
                        "tract": "37025042202"
                      },
                      "status": "found",
                      "reason": null,
                      "message": null,
                      "area": {
                        "level": "tract",
                        "geoid": "37025042202",
                        "name": "Census tract 422.02, Cabarrus County, North Carolina"
                      },
                      "location": null,
                      "rents": [
                        {
                          "bedrooms": 0,
                          "typical": 1290,
                          "low": 1060,
                          "high": 1590
                        },
                        {
                          "bedrooms": 1,
                          "typical": 1400,
                          "low": 1160,
                          "high": 1690
                        },
                        {
                          "bedrooms": 2,
                          "typical": 1590,
                          "low": 1330,
                          "high": 1880
                        },
                        {
                          "bedrooms": 3,
                          "typical": 1910,
                          "low": 1560,
                          "high": 2220
                        },
                        {
                          "bedrooms": 4,
                          "typical": 2330,
                          "low": 1910,
                          "high": 2810
                        }
                      ],
                      "yearly_growth_percent": 4.0,
                      "fair_market_rent": {
                        "fiscal_year": 2027,
                        "geography": {
                          "level": "zip",
                          "zip_codes": [
                            "28025"
                          ],
                          "hud_areas": []
                        },
                        "rents": [
                          {
                            "bedrooms": 0,
                            "fmr": 1340,
                            "low": 1340,
                            "high": 1340,
                            "percent_90": 1206,
                            "percent_110": 1474
                          },
                          {
                            "bedrooms": 1,
                            "fmr": 1400,
                            "low": 1400,
                            "high": 1400,
                            "percent_90": 1260,
                            "percent_110": 1540
                          },
                          {
                            "bedrooms": 2,
                            "fmr": 1520,
                            "low": 1520,
                            "high": 1520,
                            "percent_90": 1368,
                            "percent_110": 1672
                          },
                          {
                            "bedrooms": 3,
                            "fmr": 1860,
                            "low": 1860,
                            "high": 1860,
                            "percent_90": 1674,
                            "percent_110": 2046
                          },
                          {
                            "bedrooms": 4,
                            "fmr": 2360,
                            "low": 2360,
                            "high": 2360,
                            "percent_90": 2124,
                            "percent_110": 2596
                          }
                        ]
                      }
                    }
                  ],
                  "rent_checks_used_this_month": 1,
                  "rent_checks_left_this_month": 99,
                  "rent_checks_per_month": 100,
                  "rent_checks_purchased_left": 0,
                  "resets_at": "2026-12-01T00:00:00-05:00"
                }
              }
            },
            "headers": {
              "Idempotent-Replayed": {
                "description": "`true` when the response is a replay of an earlier request with the same `Idempotency-Key`.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Your request has invalid fields. Invalid request.",
            "x-problem-types": [
              {
                "slug": "validation-error",
                "title": "Your request has invalid fields",
                "description": "Some fields are invalid. `errors` lists each one and what is wrong with it."
              },
              {
                "slug": "invalid-request",
                "title": "Invalid request",
                "description": "The request can’t be read, for example malformed JSON or an `Idempotency-Key` that isn’t 1 to 255 visible ASCII characters."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://www.pricedna.co/api#error-validation-error",
                  "title": "Your request has invalid fields",
                  "status": 400,
                  "detail": "Send at most 100 places in one request. This one has 120.",
                  "errors": [
                    {
                      "field": "places",
                      "detail": "Send at most 100 places in one request. This one has 120."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "x-problem-types": [
              {
                "slug": "unauthorized",
                "title": "Missing or invalid API key",
                "description": "The API key is missing or not valid."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "x-problem-types": [
              {
                "slug": "forbidden",
                "title": "Forbidden",
                "description": "This key can’t make this request."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Request in progress.",
            "x-problem-types": [
              {
                "slug": "request-in-progress",
                "title": "Request in progress",
                "description": "A request with this `Idempotency-Key` is still running. Retry after the seconds in `Retry-After`."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 5
                }
              }
            }
          },
          "422": {
            "description": "Idempotency key reused.",
            "x-problem-types": [
              {
                "slug": "idempotency-key-reused",
                "title": "Idempotency key reused",
                "description": "This `Idempotency-Key` was already used with a different body. Send a new key."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests, or no rent checks left this month.",
            "x-problem-types": [
              {
                "slug": "rate-limited",
                "title": "Too many requests",
                "description": "Too many requests in a short time. Nothing is counted. Wait a moment and retry."
              },
              {
                "slug": "no-rent-checks-left",
                "title": "No rent checks left this month",
                "description": "More places than you have rent checks left this month. Nothing is counted. Send fewer places, or wait until the 1st; `rent_checks_left` says how many are left."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://www.pricedna.co/api#error-no-rent-checks-left",
                  "title": "No rent checks left this month",
                  "status": 429,
                  "detail": "You have 5 rent checks left this month. They reset on the 1st.",
                  "code": "MONTHLY_RENT_CHECKS_USED",
                  "rent_checks_left": 5,
                  "resets_at": "2026-12-01T00:00:00-05:00",
                  "rent_checks_per_month": 100,
                  "rent_checks_purchased_left": 0
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds until your rent checks reset.",
                "schema": {
                  "type": "integer",
                  "example": 18000
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable.",
            "x-problem-types": [
              {
                "slug": "service-unavailable",
                "title": "Service unavailable",
                "description": "The service had a problem. Retry shortly."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "Server error.",
            "x-problem-types": [
              {
                "slug": "server-error",
                "title": "Server error",
                "description": "The service had a problem. Retry shortly."
              }
            ],
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PriceDNA-API-Key",
        "description": "Your secret API key. Keep it server-side only."
      }
    },
    "schemas": {
      "AnalyzeRequest": {
        "type": "object",
        "description": "All rate and percentage parameters are plain numbers, such as `7.12` for 7.12%, not `0.0712`.",
        "required": [
          "address",
          "number_of_units"
        ],
        "properties": {
          "address": {
            "type": "string",
            "description": "Full US property address including street, city, state, and ZIP.",
            "x-group": "Property & Goal"
          },
          "number_of_units": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "description": "Total rentable units at the property.",
            "x-group": "Property & Goal"
          },
          "asking_price": {
            "type": "integer",
            "minimum": 50000,
            "maximum": 100000000,
            "x-unit": "$",
            "description": "Purchase price in USD. Enables cash-on-cash, DSCR, and ROI calculations.",
            "x-group": "Property & Goal"
          },
          "monthly_rent": {
            "type": "integer",
            "minimum": 200,
            "maximum": 25000,
            "x-unit": "$",
            "description": "Average monthly rent per unit in USD. Defaults to local market rent.",
            "x-group": "Property & Goal"
          },
          "goal": {
            "$ref": "#/components/schemas/GoalRequest",
            "x-group": "Property & Goal"
          },
          "goal_metric": {
            "type": "string",
            "enum": [
              "cash_on_cash_return",
              "debt_service_coverage_ratio",
              "cash_velocity"
            ],
            "deprecated": true,
            "description": "Same as `goal.metric`. Still accepted.",
            "x-group": "Property & Goal"
          },
          "goal_target": {
            "type": "number",
            "deprecated": true,
            "description": "Same as `goal.target`. Still accepted.",
            "x-group": "Property & Goal"
          },
          "vacancy_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 30,
            "x-unit": "%",
            "description": "Expected vacancy as a percentage. Under 4% is tight; above 8% suggests softer demand. Defaults to market average.",
            "x-group": "Performance & Stabilization"
          },
          "management_fee_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 25,
            "x-unit": "%",
            "description": "Property management fee as a percentage of gross rent. Typically 3 to 12%.",
            "x-group": "Performance & Stabilization"
          },
          "upkeep_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 30,
            "x-unit": "%",
            "description": "Routine repairs and maintenance as a percentage of gross rent. Defaults to 10%.",
            "x-group": "Performance & Stabilization"
          },
          "reserve_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 30,
            "x-unit": "%",
            "description": "Reserve for replacements such as the roof, HVAC and water heater, as a percentage of gross rent. Defaults to 5%.",
            "x-group": "Performance & Stabilization"
          },
          "make_ready_amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000,
            "x-unit": "$",
            "description": "One-time post-acquisition touch-up budget in USD. Often $0 for stabilized properties.",
            "x-group": "Performance & Stabilization"
          },
          "total_monthly_other_expenses": {
            "type": "integer",
            "minimum": 0,
            "maximum": 25000,
            "x-unit": "$/month",
            "description": "Total landlord-paid monthly expenses not captured elsewhere (utilities, HOA, etc.) in USD for the whole property.",
            "x-group": "Performance & Stabilization"
          },
          "mortgage_interest_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 25,
            "x-unit": "%",
            "description": "Annual mortgage interest rate as a percentage. Defaults to current market rate for the location. A 0.5% change ≈ $180/mo on a $400k loan.",
            "x-group": "Financing"
          },
          "mortgage_term": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30,
            "x-unit": "years",
            "description": "Loan term in years. Defaults to 30. Common values: 10, 15, 20, 25, 30.",
            "x-group": "Financing"
          },
          "down_payment_percentage": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "x-unit": "%",
            "description": "Down payment as a percentage of purchase price. Typical: 20 to 25% for conventional loans.",
            "x-group": "Financing"
          },
          "closing_cost_percentage": {
            "type": "number",
            "minimum": 0,
            "maximum": 10,
            "x-unit": "%",
            "description": "Closing costs as a percentage of purchase price. Typically 2 to 5%; varies by lender and local taxes.",
            "x-group": "Financing"
          },
          "property_tax_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 5,
            "x-unit": "%",
            "description": "Annual property tax as a percentage of assessed value. Varies by county and local levy.",
            "x-group": "Location Dynamics"
          },
          "property_insurance_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 8,
            "x-unit": "%",
            "description": "Standard property insurance as a percentage of property value annually. Typically 0.3 to 0.8%; higher in coastal areas.",
            "x-group": "Insurance"
          },
          "flood_insurance_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 8,
            "x-unit": "%",
            "description": "Flood insurance as a percentage of property value. Applies only in flood zones; varies by elevation and coverage.",
            "x-group": "Insurance"
          },
          "wind_insurance_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 8,
            "x-unit": "%",
            "description": "Wind insurance as a percentage of property value. Common in hurricane-prone regions.",
            "x-group": "Insurance"
          },
          "market_cap_rate": {
            "type": "number",
            "minimum": 1,
            "maximum": 25,
            "x-unit": "%",
            "description": "For 2+ units: the market cap rate the income value uses. Defaults to the county’s multifamily market cap rate, a starting point you can change. Ignored for a single house.",
            "x-group": "Market value"
          }
        }
      },
      "GoalRequest": {
        "type": "object",
        "description": "Your goal: the metric to optimize for and its target.",
        "properties": {
          "metric": {
            "type": "string",
            "enum": [
              "cash_on_cash_return",
              "debt_service_coverage_ratio",
              "cash_velocity"
            ],
            "description": "Return metric to optimize for. Defaults to `cash_on_cash_return`."
          },
          "target": {
            "type": "number",
            "description": "Target for `metric`. Cash-on-cash return uses a percentage, DSCR uses a ratio, and cash velocity uses monthly dollars per unit. Defaults to a location-calibrated value."
          }
        }
      },
      "Report": {
        "type": "object",
        "description": "One object per report section, in report order.",
        "required": [
          "report_id",
          "created_at",
          "links",
          "property",
          "goal",
          "estimate",
          "projections",
          "location",
          "neighborhood",
          "nearby_influences",
          "market_pulse",
          "deal_metrics",
          "assumptions"
        ],
        "x-page-rows": [
          {
            "section": "estimate",
            "keys": [
              "report_id",
              "created_at",
              "links",
              "property",
              "goal",
              "estimate"
            ]
          },
          {
            "section": "projections",
            "keys": [
              "projections"
            ]
          },
          {
            "section": "location",
            "keys": [
              "location"
            ]
          },
          {
            "section": "neighborhood",
            "keys": [
              "neighborhood"
            ]
          },
          {
            "section": "nearby_influences",
            "keys": [
              "nearby_influences",
              "market_pulse"
            ]
          },
          {
            "section": "deal_metrics",
            "keys": [
              "deal_metrics"
            ]
          },
          {
            "section": "assumptions",
            "keys": [
              "assumptions"
            ]
          }
        ],
        "properties": {
          "report_id": {
            "type": "string",
            "description": "The report’s ID."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the report was made, ISO 8601 in UTC."
          },
          "links": {
            "$ref": "#/components/schemas/Links"
          },
          "property": {
            "$ref": "#/components/schemas/Property"
          },
          "goal": {
            "$ref": "#/components/schemas/GoalResult"
          },
          "estimate": {
            "$ref": "#/components/schemas/Estimate"
          },
          "projections": {
            "$ref": "#/components/schemas/Projections"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "neighborhood": {
            "$ref": "#/components/schemas/Neighborhood"
          },
          "nearby_influences": {
            "$ref": "#/components/schemas/NearbyInfluences"
          },
          "market_pulse": {
            "$ref": "#/components/schemas/MarketPulse"
          },
          "deal_metrics": {
            "$ref": "#/components/schemas/DealMetrics"
          },
          "assumptions": {
            "$ref": "#/components/schemas/Assumptions"
          }
        }
      },
      "Links": {
        "type": "object",
        "properties": {
          "report": {
            "type": "string",
            "format": "uri",
            "description": "The report in the PriceDNA app."
          }
        }
      },
      "Property": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          },
          "asking_price": {
            "type": [
              "integer",
              "null"
            ],
            "description": "`null` when the property is unpriced."
          },
          "units": {
            "type": "integer"
          },
          "flood_zone": {
            "type": "boolean"
          },
          "coastal_flood_zone": {
            "type": "boolean"
          }
        }
      },
      "GoalResult": {
        "type": "object",
        "properties": {
          "metric": {
            "type": "string",
            "enum": [
              "cash_on_cash_return",
              "cap_rate",
              "debt_service_coverage_ratio",
              "cash_velocity"
            ]
          },
          "target": {
            "type": "number"
          },
          "achieved": {
            "type": "number"
          }
        }
      },
      "Estimate": {
        "type": "object",
        "title": "PriceDNA Estimate™",
        "x-report-section": "PriceDNA Estimate",
        "description": "The purchase price your goal can support, and how far the asking price is from it.",
        "properties": {
          "price": {
            "type": "integer",
            "description": "The goal-convergent price."
          },
          "gap_percent": {
            "type": [
              "number",
              "null"
            ],
            "description": "How far the asking price is above it."
          },
          "summary": {
            "type": "string",
            "description": "What the gap means, in words."
          },
          "tone": {
            "type": "string",
            "enum": [
              "success",
              "neutral",
              "warning"
            ],
            "description": "The tone of the gap message: `success`, `neutral` or `warning`."
          },
          "market_value": {
            "type": [
              "object",
              "null"
            ],
            "description": "The market-facing number the report shows beside the estimate. For 2+ units, the income value: net operating income at the market cap rate, with tax and insurance loaded into the rate. For a single house, what single-family homes in the neighborhood appraised for, from FHFA. It never moves the estimate. Null when there is none.",
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "income",
                  "neighborhood_appraisals"
                ],
                "description": "`income` for 2+ units, `neighborhood_appraisals` for a single house."
              },
              "value": {
                "type": "integer",
                "description": "The income value, or the neighborhood’s median appraised value."
              },
              "net_operating_income": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "For `income`: the yearly NOI the value rests on."
              },
              "market_cap_rate": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "For `income`: the market cap rate used, as a percent number."
              },
              "low": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "For `neighborhood_appraisals`: the 25th percentile appraised value."
              },
              "high": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "For `neighborhood_appraisals`: the 75th percentile appraised value."
              },
              "year": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "For `neighborhood_appraisals`: the year of the appraisals."
              },
              "level": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "tract",
                  "county",
                  null
                ],
                "description": "For `neighborhood_appraisals`: `tract`, or `county` where the tract has too few appraisals to publish."
              },
              "source": {
                "type": "string",
                "description": "`PriceDNA income value` or `FHFA Uniform Appraisal Dataset`."
              }
            }
          }
        }
      },
      "Projections": {
        "type": "object",
        "title": "Projected ROI path",
        "x-report-section": "Projected ROI path",
        "description": "The return at 3, 5, 7 and 10 years, expected and in a downturn. Both use the same fields per year, so code that reads one reads the other.",
        "properties": {
          "cash_invested": {
            "type": "integer"
          },
          "expected": {
            "$ref": "#/components/schemas/ProjectionScenario",
            "description": "Price growth from the county’s market phase, rent growth from PriceDNA’s rent model."
          },
          "downturn": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DownturnScenario"
              },
              {
                "type": "null"
              }
            ],
            "description": "The same deal through the area’s hardest downturn on record, with the county’s rents from those years. `null` when the area has none."
          },
          "market_phase": {
            "type": [
              "object",
              "null"
            ],
            "description": "The county’s market phase the expected price growth comes from: what the market is doing now and what usually followed in past markets. History, not a prediction. Null when the county has too little price history.",
            "properties": {
              "phase": {
                "type": "string",
                "enum": [
                  "downturn",
                  "recovery",
                  "boom",
                  "steady",
                  "slowed"
                ],
                "description": "`downturn`, `recovery`, `boom`, `steady` or `slowed`."
              },
              "scope": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "broad",
                  "local",
                  null
                ],
                "description": "For `downturn` and `recovery`: `broad` when the state is also in a downturn, else `local`."
              },
              "years_in_phase": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "How many years in a row the county has been in this phase."
              },
              "typical_years_left": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "How many more years such stretches usually lasted in past markets."
              },
              "usually_followed_by": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The phase such stretches most often turned into."
              },
              "area": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The county the phase describes."
              },
              "summary": {
                "type": "string",
                "description": "The same two sentences the report shows."
              }
            }
          }
        }
      },
      "ProjectionScenario": {
        "type": "object",
        "properties": {
          "years": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProjectionYear"
            }
          }
        }
      },
      "DownturnScenario": {
        "type": "object",
        "properties": {
          "replays": {
            "$ref": "#/components/schemas/DownturnReplay",
            "description": "Which drop: area, years, how far prices fell."
          },
          "years": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProjectionYear"
            }
          }
        }
      },
      "DownturnReplay": {
        "type": "object",
        "properties": {
          "area": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "start_year": {
            "type": "integer"
          },
          "end_year": {
            "type": "integer"
          },
          "price_drop": {
            "type": "number"
          },
          "rents_replayed": {
            "type": "boolean"
          }
        }
      },
      "ProjectionYear": {
        "type": "object",
        "required": [
          "years"
        ],
        "properties": {
          "years": {
            "type": "integer"
          },
          "appreciation": {
            "type": "integer"
          },
          "cash_flow": {
            "type": "integer"
          },
          "loan_paydown": {
            "type": "integer"
          },
          "upfront_costs": {
            "type": "integer",
            "description": "Closing costs and make-ready."
          },
          "net_gain": {
            "type": "integer",
            "description": "Appreciation, cash flow and loan paydown, after upfront costs."
          },
          "roi": {
            "type": "number",
            "description": "`net_gain` as a percent of `cash_invested`."
          },
          "equity_multiple": {
            "type": "number"
          }
        }
      },
      "Location": {
        "type": "object",
        "title": "PriceDNA Location Score™",
        "x-report-section": "Location Score",
        "description": "How much the location supports the deal, from 0 to 100, and the six factors behind it, heaviest first.",
        "properties": {
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "0 to 100."
          },
          "label": {
            "type": "string",
            "enum": [
              "excellent",
              "very good",
              "good",
              "fair",
              "poor"
            ],
            "description": "Excellent, very good, good, fair or poor."
          },
          "factors": {
            "type": "array",
            "description": "Each factor’s weight and rating.",
            "items": {
              "$ref": "#/components/schemas/LocationFactor"
            }
          }
        }
      },
      "LocationFactor": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "weight": {
            "type": "number"
          },
          "rating": {
            "type": "string"
          }
        }
      },
      "Neighborhood": {
        "type": "array",
        "title": "Neighborhood",
        "x-report-section": "Neighborhood",
        "description": "Who lives around the property and how deep the renter pool is, within 1, 3 and 5 miles. Census ACS.",
        "items": {
          "$ref": "#/components/schemas/NeighborhoodRing"
        }
      },
      "NeighborhoodRing": {
        "type": "object",
        "properties": {
          "radius_mi": {
            "type": "number"
          },
          "population": {
            "type": "integer"
          },
          "households": {
            "type": "integer"
          },
          "renter_occupied": {
            "type": "number",
            "description": "Share of homes rented, percent."
          },
          "renter_age": {
            "type": "number",
            "description": "Share of adults in prime renting ages."
          },
          "college_educated": {
            "type": "number"
          },
          "vacant": {
            "type": "number"
          }
        }
      },
      "NearbyInfluences": {
        "type": "array",
        "title": "Nearby influences on resale",
        "description": "What a listing won’t mention, within each category’s search radius. An empty `found` means nothing was detected.",
        "items": {
          "$ref": "#/components/schemas/NearbyInfluence"
        }
      },
      "NearbyInfluence": {
        "type": "object",
        "properties": {
          "category": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "radius_mi": {
            "type": "number"
          },
          "found": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NearbyPlace"
            }
          }
        }
      },
      "NearbyPlace": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "distance_mi": {
            "type": "number"
          }
        }
      },
      "MarketPulse": {
        "type": "array",
        "title": "Market pulse",
        "items": {
          "$ref": "#/components/schemas/MarketPulseItem"
        }
      },
      "MarketPulseItem": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "DealMetrics": {
        "type": "object",
        "title": "Deal metrics",
        "x-report-section": "Deal metrics",
        "description": "The ratios an investor checks. Return, financing and operating metrics are at the PriceDNA Estimate; the 1% rule and GRM at the asking price.",
        "properties": {
          "cash_velocity": {
            "type": "number"
          },
          "cash_on_cash_return": {
            "type": "number"
          },
          "dscr": {
            "type": "number"
          },
          "noi": {
            "type": "integer"
          },
          "operating_cap_rate": {
            "type": "number"
          },
          "opex_ratio": {
            "type": "number"
          },
          "mortgage_payment": {
            "type": "integer"
          },
          "total_investment": {
            "type": "integer"
          },
          "one_percent_rule": {
            "type": "number"
          },
          "grm": {
            "type": "number"
          }
        }
      },
      "Assumptions": {
        "type": "array",
        "title": "Assumptions",
        "x-report-section": "Assumptions",
        "description": "Every input the report used. `entered` is true for values you sent and false for PriceDNA’s figures, the same as the report’s Entered tag.",
        "items": {
          "$ref": "#/components/schemas/Assumption"
        }
      },
      "Assumption": {
        "type": "object",
        "required": [
          "name",
          "label",
          "value",
          "entered"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "value": {
            "type": [
              "number",
              "string"
            ]
          },
          "unit": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "entered": {
            "type": "boolean"
          }
        }
      },
      "Problem": {
        "type": "object",
        "title": "Errors",
        "description": "Errors usually arrive as problem details (RFC 9457), sent as `application/problem+json`.",
        "required": [
          "type",
          "title",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference",
            "description": "A link to the problem type’s explanation on the API page, `https://www.pricedna.co/api#error-<slug>`."
          },
          "title": {
            "type": "string",
            "description": "The problem type’s fixed title."
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string",
            "description": "More about this occurrence, or the title when there is nothing more specific."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProblemFieldError"
            }
          }
        }
      },
      "ProblemFieldError": {
        "type": "object",
        "required": [
          "field",
          "detail"
        ],
        "properties": {
          "field": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          }
        }
      },
      "GeocodeRequest": {
        "type": "object",
        "required": [
          "addresses"
        ],
        "properties": {
          "addresses": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "string"
            },
            "x-group": "Body",
            "description": "US addresses as text: house number, street, city or ZIP, and state. One row comes back for each, in the same order."
          },
          "census": {
            "type": "boolean",
            "default": false,
            "x-group": "Body",
            "description": "Add each row’s census tract (`tract`): 1 more point a row."
          },
          "flood": {
            "type": "boolean",
            "default": false,
            "x-group": "Body",
            "description": "Add each row’s flood zone and coastal risk (`flood`): 1 more point a row."
          }
        }
      },
      "GeoPoint": {
        "type": "object",
        "required": [
          "lat",
          "lng"
        ],
        "properties": {
          "lat": {
            "type": "number",
            "description": "Latitude in decimal degrees."
          },
          "lng": {
            "type": "number",
            "description": "Longitude in decimal degrees."
          }
        }
      },
      "ReverseRequest": {
        "type": "object",
        "required": [
          "points"
        ],
        "properties": {
          "points": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/GeoPoint"
            },
            "x-group": "Body",
            "description": "Points in the United States. One row comes back for each, in the same order."
          },
          "census": {
            "type": "boolean",
            "default": false,
            "x-group": "Body",
            "description": "Add each row’s census tract (`tract`): 1 more point a row."
          },
          "flood": {
            "type": "boolean",
            "default": false,
            "x-group": "Body",
            "description": "Add each row’s flood zone and coastal risk (`flood`): 1 more point a row."
          }
        }
      },
      "GeoState": {
        "type": "object",
        "properties": {
          "abbr": {
            "type": "string",
            "description": "Two-letter state code, such as `NC`."
          },
          "name": {
            "type": "string",
            "description": "State name."
          }
        }
      },
      "GeoCounty": {
        "type": "object",
        "properties": {
          "fips": {
            "type": "string",
            "description": "Five-digit county FIPS code."
          },
          "name": {
            "type": "string",
            "description": "County name, such as Cabarrus County."
          }
        }
      },
      "GeoTract": {
        "type": "object",
        "properties": {
          "geoid": {
            "type": "string",
            "description": "The tract’s 11-digit census code: state, county and tract."
          },
          "number": {
            "type": "string",
            "description": "The tract number as the Census Bureau writes it, such as `406` or `11.01`."
          }
        }
      },
      "GeoFlood": {
        "type": "object",
        "properties": {
          "zone": {
            "type": [
              "string",
              "null"
            ],
            "description": "FEMA’s zone code at the point for high-risk, moderate-risk and undetermined zones, such as `AE` or `D`. Null elsewhere."
          },
          "risk": {
            "type": "string",
            "enum": [
              "high",
              "moderate",
              "undetermined",
              "minimal",
              "not_mapped",
              "unknown"
            ],
            "description": "The flood risk FEMA’s map gives the point.",
            "x-enum-descriptions": {
              "high": "In a FEMA high-risk zone (A or V zones).",
              "moderate": "In a moderate-risk zone.",
              "undetermined": "In a zone where FEMA has not determined the risk (D).",
              "minimal": "Mapped, with minimal risk.",
              "not_mapped": "FEMA has no flood map for the point.",
              "unknown": "The flood map could not be read for this lookup. Send it again."
            }
          },
          "in_high_risk_zone": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "True inside a FEMA high-risk zone. Null when the risk is `unknown`."
          },
          "coastal_county": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "True when the county touches the open coastline, ocean, Gulf or Great Lakes (Census Bureau TIGER/Line coastline), or FEMA's National Risk Index rates coastal flooding in it, which covers bays, harbors and estuaries."
          },
          "coastal_flood_risk": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "very_high",
              "relatively_high",
              "relatively_moderate",
              "relatively_low",
              "very_low",
              "not_rated",
              null
            ],
            "description": "The census tract’s coastal flooding rating from FEMA’s National Risk Index. Null where coastal flooding doesn’t apply.",
            "x-enum-descriptions": {
              "very_high": "Very high.",
              "relatively_high": "Relatively high.",
              "relatively_moderate": "Relatively moderate.",
              "relatively_low": "Relatively low.",
              "very_low": "Very low.",
              "not_rated": "FEMA gives the tract no rating, or has too little data to rate it."
            }
          }
        }
      },
      "NearestAddress": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "The closest address to the point."
          },
          "meters": {
            "type": "number",
            "description": "How far it is from the point."
          }
        }
      },
      "GeocodeRow": {
        "type": "object",
        "title": "Rows",
        "description": "Every row has every field, in the same order. A field that doesn’t apply, or that the request didn’t ask for, is null.",
        "x-statuses": [
          {
            "status": "placed",
            "charged": true,
            "description": "Placed. Every field is filled where it applies."
          },
          {
            "status": "not_found",
            "charged": true,
            "description": "A complete address we could not place. `message` says why, with the known house numbers when the number is out of range."
          },
          {
            "status": "invalid",
            "charged": true,
            "description": "Not an address or point we can read."
          },
          {
            "status": "outside_coverage",
            "charged": true,
            "description": "Outside the 50 states and DC."
          },
          {
            "status": "error",
            "charged": false,
            "description": "We couldn’t read our own address data (`lookup_unavailable`), the lookup failed (`lookup_failed`), or the request ran out of time before this row (`timeout`). Send it again."
          }
        ],
        "required": [
          "input",
          "status",
          "reason",
          "message",
          "address",
          "lat",
          "lng",
          "accuracy",
          "state",
          "county",
          "city",
          "township",
          "zip",
          "tract",
          "tribal_land",
          "flood"
        ],
        "properties": {
          "input": {
            "description": "What you sent for this row, as sent."
          },
          "status": {
            "type": "string",
            "enum": [
              "placed",
              "not_found",
              "invalid",
              "outside_coverage",
              "error"
            ],
            "description": "Whether the row was placed. Every status but `error` is charged its points."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "number_out_of_range",
              "unknown_street",
              "not_found",
              "incomplete",
              "not_text",
              "bad_point",
              "outside_coverage",
              "lookup_unavailable",
              "lookup_failed",
              "timeout",
              null
            ],
            "description": "Why a row was not placed. Null when it was. Every reason is in the Reasons table below.",
            "x-reasons": [
              {
                "reason": "number_out_of_range",
                "status": "not_found",
                "message_description": "Names the house numbers we know on that street, such as: We don't know 290 on Main St in Springfield. Known numbers run from 100 to 199. Check the address and try again."
              },
              {
                "reason": "unknown_street",
                "status": "not_found",
                "message": "We can't find this street yet. If it's new, enter a nearby address."
              },
              {
                "reason": "not_found",
                "status": "not_found",
                "message": "We couldn't find that address."
              },
              {
                "reason": "incomplete",
                "status": "invalid",
                "message": "Enter the full address: house number, street, city or ZIP, and state."
              },
              {
                "reason": "not_text",
                "status": "invalid",
                "message": "Send the address as text: house number, street, city or ZIP, and state."
              },
              {
                "reason": "bad_point",
                "status": "invalid",
                "message": "Send a latitude and longitude in the United States."
              },
              {
                "reason": "outside_coverage",
                "status": "outside_coverage",
                "message": "We cover addresses in the 50 states and DC."
              },
              {
                "reason": "lookup_unavailable",
                "status": "error",
                "message": "We couldn't finish this lookup. Send it again in a minute."
              },
              {
                "reason": "lookup_failed",
                "status": "error",
                "message": "We couldn't finish this lookup. Send it again in a minute."
              },
              {
                "reason": "timeout",
                "status": "error",
                "message": "We ran out of time before this row. Send it again; it was not counted."
              }
            ]
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "The reason in plain words. Null when the row was placed."
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "The address as placed. Null on reverse rows; see `nearest_address`."
          },
          "lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Latitude in decimal degrees."
          },
          "lng": {
            "type": [
              "number",
              "null"
            ],
            "description": "Longitude in decimal degrees."
          },
          "accuracy": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "address_point",
              "park",
              "neighbor_interpolated",
              "street_range",
              "street_range_extended",
              null
            ],
            "description": "How the address was placed. Null on reverse rows, where the point is yours.",
            "x-enum-descriptions": {
              "address_point": "A stored point for this very address.",
              "park": "A national park’s own coordinates.",
              "neighbor_interpolated": "Between neighbors’ stored points on the same side of the street.",
              "street_range": "Along the street, from its range of house numbers.",
              "street_range_extended": "Just past the street’s known house numbers. An estimate."
            }
          },
          "state": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/GeoState"
              },
              {
                "type": "null"
              }
            ],
            "description": "The state."
          },
          "county": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/GeoCounty"
              },
              {
                "type": "null"
              }
            ],
            "description": "The county, or the county equivalent such as a parish or borough."
          },
          "city": {
            "type": [
              "string",
              "null"
            ],
            "description": "The city, town or village the point is in. Null outside one."
          },
          "township": {
            "type": [
              "string",
              "null"
            ],
            "description": "The town or township, where it is a separate place from the city."
          },
          "zip": {
            "type": [
              "string",
              "null"
            ],
            "description": "The five-digit ZIP code area the point is in."
          },
          "tract": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/GeoTract"
              },
              {
                "type": "null"
              }
            ],
            "description": "The census tract, with `\"census\": true`. Null otherwise."
          },
          "tribal_land": {
            "type": [
              "string",
              "null"
            ],
            "description": "The tribal jurisdiction’s name on tribal land. Null elsewhere."
          },
          "flood": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/GeoFlood"
              },
              {
                "type": "null"
              }
            ],
            "description": "FEMA flood zone and coastal risk at the point, with `\"flood\": true`. Null otherwise."
          }
        }
      },
      "ReverseRow": {
        "allOf": [
          {
            "$ref": "#/components/schemas/GeocodeRow"
          },
          {
            "type": "object",
            "required": [
              "nearest_address",
              "nearest_address_unavailable"
            ],
            "properties": {
              "nearest_address": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/NearestAddress"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Reverse rows only: the closest address within 100 meters, and how far. Null past that, or when the search couldn’t finish."
              },
              "nearest_address_unavailable": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "Reverse rows only: true when the search for the nearest address couldn’t finish, so a null `nearest_address` doesn’t mean none within 100 meters. Null on rows that weren’t placed."
              }
            }
          }
        ]
      },
      "GeocodeResponse": {
        "type": "object",
        "required": [
          "results",
          "points_used_today",
          "points_left_today",
          "points_per_day",
          "points_purchased_left",
          "resets_at"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GeocodeRow"
            },
            "description": "One row per address or point, in the order sent."
          },
          "points_used_today": {
            "type": "integer",
            "description": "Points your account has used today, across the API and the site."
          },
          "points_left_today": {
            "type": "integer",
            "description": "Points left today."
          },
          "points_per_day": {
            "type": "integer",
            "description": "Your plan’s points a day."
          },
          "points_purchased_left": {
            "type": "integer",
            "description": "Points bought in packs and not yet spent. Used once today’s points are gone; they carry over while your account is open."
          },
          "resets_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the count resets: midnight Eastern time."
          }
        }
      },
      "ReverseResponse": {
        "type": "object",
        "required": [
          "results",
          "points_used_today",
          "points_left_today",
          "points_per_day",
          "points_purchased_left",
          "resets_at"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReverseRow"
            },
            "description": "One row per address or point, in the order sent."
          },
          "points_used_today": {
            "type": "integer",
            "description": "Points your account has used today, across the API and the site."
          },
          "points_left_today": {
            "type": "integer",
            "description": "Points left today."
          },
          "points_per_day": {
            "type": "integer",
            "description": "Your plan’s points a day."
          },
          "points_purchased_left": {
            "type": "integer",
            "description": "Points bought in packs and not yet spent. Used once today’s points are gone; they carry over while your account is open."
          },
          "resets_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the count resets: midnight Eastern time."
          }
        }
      },
      "RentPlaceText": {
        "type": "string",
        "title": "Address text",
        "description": "A US address. Answers for its census tract.",
        "example": "123 Union St S, Concord, NC 28025"
      },
      "RentPlaceAddress": {
        "type": "object",
        "title": "Address",
        "required": [
          "address"
        ],
        "properties": {
          "address": {
            "type": "string"
          }
        },
        "description": "The same, as an object. Answers for its census tract.",
        "example": {
          "address": "123 Union St S, Concord, NC 28025"
        }
      },
      "RentPlacePoint": {
        "type": "object",
        "title": "Point",
        "required": [
          "lat",
          "lng"
        ],
        "properties": {
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          }
        },
        "description": "A point in the United States. Answers for its census tract.",
        "example": {
          "lat": 35.408416,
          "lng": -80.578372
        }
      },
      "RentPlaceTract": {
        "type": "object",
        "title": "Census tract",
        "required": [
          "tract"
        ],
        "properties": {
          "tract": {
            "type": "string"
          }
        },
        "description": "An 11-digit census tract code.",
        "example": {
          "tract": "37025042202"
        }
      },
      "RentPlaceZip": {
        "type": "object",
        "title": "ZIP code",
        "required": [
          "zip"
        ],
        "properties": {
          "zip": {
            "type": "string"
          }
        },
        "description": "A five-digit ZIP code.",
        "example": {
          "zip": "28025"
        }
      },
      "RentPlaceCity": {
        "type": "object",
        "title": "City",
        "required": [
          "city",
          "state"
        ],
        "properties": {
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          }
        },
        "description": "A city or town with its two-letter state.",
        "example": {
          "city": "Concord",
          "state": "NC"
        }
      },
      "RentPlaceCounty": {
        "type": "object",
        "title": "County",
        "required": [
          "county"
        ],
        "properties": {
          "county": {
            "type": "string"
          }
        },
        "description": "A five-digit county FIPS code.",
        "example": {
          "county": "37025"
        }
      },
      "RentPlace": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/RentPlaceText"
          },
          {
            "$ref": "#/components/schemas/RentPlaceAddress"
          },
          {
            "$ref": "#/components/schemas/RentPlacePoint"
          },
          {
            "$ref": "#/components/schemas/RentPlaceTract"
          },
          {
            "$ref": "#/components/schemas/RentPlaceZip"
          },
          {
            "$ref": "#/components/schemas/RentPlaceCity"
          },
          {
            "$ref": "#/components/schemas/RentPlaceCounty"
          }
        ]
      },
      "RentRequest": {
        "type": "object",
        "required": [
          "places"
        ],
        "properties": {
          "places": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/RentPlace"
            },
            "x-group": "Body",
            "description": "Places of any kind, mixed freely. One row comes back for each, in the same order."
          }
        }
      },
      "RentArea": {
        "type": "object",
        "properties": {
          "level": {
            "type": "string",
            "enum": [
              "tract",
              "zip",
              "city",
              "county"
            ],
            "description": "The area the figures describe.",
            "x-enum-descriptions": {
              "tract": "The census tract of an address or point, or the tract you sent.",
              "zip": "The ZIP code you sent.",
              "city": "The city or town you sent.",
              "county": "The county you sent, or the county of a tract without figures of its own."
            }
          },
          "geoid": {
            "type": [
              "string",
              "null"
            ],
            "description": "The area’s code: tract, ZIP or county FIPS. Null for a city."
          },
          "name": {
            "type": "string",
            "description": "The area’s name."
          }
        }
      },
      "RentLocation": {
        "type": "object",
        "properties": {
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "The address as placed. Null for a point."
          },
          "lat": {
            "type": "number",
            "description": "Latitude."
          },
          "lng": {
            "type": "number",
            "description": "Longitude."
          }
        }
      },
      "RentFigure": {
        "type": "object",
        "properties": {
          "bedrooms": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4,
            "description": "0 for a studio, up to 4 bedrooms."
          },
          "typical": {
            "type": "integer",
            "description": "The middle rent for a home of that size in the area, on the lease, without utilities. Dollars a month."
          },
          "low": {
            "type": "integer",
            "description": "The low end of the range. For a census tract, the 25th percentile of rents recent movers pay. For a ZIP code, city or county, the middle of its tracts' figures."
          },
          "high": {
            "type": "integer",
            "description": "The high end of the range. For a census tract, the 75th percentile of rents recent movers pay. For a ZIP code, city or county, the middle of its tracts' figures."
          }
        }
      },
      "RentHudArea": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "HUD’s code for the area, such as METRO16740M16740."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "HUD’s name for the area."
          }
        }
      },
      "RentFairMarketRentGeography": {
        "type": "object",
        "properties": {
          "level": {
            "type": "string",
            "enum": [
              "zip",
              "zip_codes",
              "hud_area"
            ],
            "description": "Where HUD’s figure comes from.",
            "x-enum-descriptions": {
              "zip": "One ZIP code’s Small Area figure: an address’s or point’s own ZIP code, or the ZIP code you sent.",
              "zip_codes": "Several ZIP codes: a tract, city or county, or an address whose label has no ZIP code.",
              "hud_area": "HUD’s figure for a metro area or county, for a ZIP code with no Small Area figure."
            }
          },
          "zip_codes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The ZIP codes whose Small Area figures were used."
          },
          "hud_areas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RentHudArea"
            },
            "description": "HUD’s metro or county areas whose figures were used, for ZIP codes with no Small Area figure. Usually empty."
          }
        }
      },
      "RentFairMarketRentFigure": {
        "type": "object",
        "properties": {
          "bedrooms": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4,
            "description": "0 for a studio, up to 4 bedrooms."
          },
          "fmr": {
            "type": [
              "integer",
              "null"
            ],
            "description": "HUD’s fair market rent, when every ZIP code used has the same one. Rent plus utilities, dollars a month. Null when the place spans ZIP codes with different figures; then see `low` and `high`."
          },
          "low": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The lowest of HUD’s figures across the ZIP codes used. Equals `fmr` when there is one figure."
          },
          "high": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The highest of HUD’s figures across the ZIP codes used. Equals `fmr` when there is one figure."
          },
          "percent_90": {
            "type": [
              "integer",
              "null"
            ],
            "description": "90% of `fmr`, HUD’s own column for a Small Area figure. Null when `fmr` is null."
          },
          "percent_110": {
            "type": [
              "integer",
              "null"
            ],
            "description": "110% of `fmr`, HUD’s own column for a Small Area figure. Null when `fmr` is null."
          }
        }
      },
      "RentFairMarketRent": {
        "type": "object",
        "description": "HUD’s Small Area Fair Market Rent for the place’s ZIP codes: rent plus utilities, a benchmark, not a voucher payment or an approved rent. Housing authorities set their own payment standards.",
        "properties": {
          "fiscal_year": {
            "type": "integer",
            "description": "HUD’s fiscal year for the figures, which starts in October of the year before."
          },
          "geography": {
            "$ref": "#/components/schemas/RentFairMarketRentGeography",
            "description": "Where HUD’s figure comes from: the ZIP codes used, or HUD’s metro or county area."
          },
          "rents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RentFairMarketRentFigure"
            },
            "description": "One entry per bedroom count, studio to 4 bedrooms."
          }
        }
      },
      "RentRow": {
        "type": "object",
        "title": "Rows",
        "description": "Every row has every field, in the same order. A field that doesn’t apply is null.",
        "x-statuses": [
          {
            "status": "found",
            "charged": true,
            "description": "Figures for the place. Every field is filled where it applies."
          },
          {
            "status": "not_found",
            "charged": true,
            "description": "We have no figures for the place, don’t know the tract code, or couldn’t place the address."
          },
          {
            "status": "invalid",
            "charged": true,
            "description": "Not a place we can read. `message` says what to send."
          },
          {
            "status": "outside_coverage",
            "charged": true,
            "description": "Outside the 50 states and DC."
          },
          {
            "status": "error",
            "charged": false,
            "description": "The lookup couldn’t finish, or the request ran out of time before this row. Send it again."
          }
        ],
        "required": [
          "input",
          "status",
          "reason",
          "message",
          "area",
          "location",
          "rents",
          "yearly_growth_percent",
          "fair_market_rent"
        ],
        "properties": {
          "input": {
            "description": "The place you sent, as sent."
          },
          "status": {
            "type": "string",
            "enum": [
              "found",
              "not_found",
              "invalid",
              "outside_coverage",
              "error"
            ],
            "description": "Whether the place has figures. Every status but `error` counts as a rent check."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "no_figures",
              "not_found",
              "number_out_of_range",
              "unknown_street",
              "unknown_tract",
              "invalid",
              "incomplete",
              "outside_coverage",
              "lookup_unavailable",
              "lookup_failed",
              "timeout",
              null
            ],
            "description": "Why a row has no figures. Null when it has. Every reason is in the Reasons table below.",
            "x-reasons": [
              {
                "reason": "no_figures",
                "status": "not_found",
                "message": "We have no rent figures for that place."
              },
              {
                "reason": "not_found",
                "status": "not_found",
                "message": "We couldn't find that address."
              },
              {
                "reason": "number_out_of_range",
                "status": "not_found",
                "message_description": "Names the house numbers we know on that street, such as: We don't know 290 on Main St in Springfield. Known numbers run from 100 to 199. Check the address and try again."
              },
              {
                "reason": "unknown_street",
                "status": "not_found",
                "message": "We can't find this street yet. If it's new, enter a nearby address."
              },
              {
                "reason": "unknown_tract",
                "status": "not_found",
                "message": "We don't know that census tract. Check its 11-digit code."
              },
              {
                "reason": "invalid",
                "status": "invalid",
                "message_description": "Says what to send for the kind of place you sent, such as: Send the ZIP code as five digits."
              },
              {
                "reason": "incomplete",
                "status": "invalid",
                "message": "Enter the full address: house number, street, city or ZIP, and state."
              },
              {
                "reason": "outside_coverage",
                "status": "outside_coverage",
                "message": "We cover addresses in the 50 states and DC."
              },
              {
                "reason": "lookup_unavailable",
                "status": "error",
                "message": "We couldn't finish this lookup. Send it again in a minute."
              },
              {
                "reason": "lookup_failed",
                "status": "error",
                "message": "We couldn't finish this lookup. Send it again in a minute."
              },
              {
                "reason": "timeout",
                "status": "error",
                "message": "We ran out of time before this row. Send it again; it was not counted."
              }
            ]
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "The reason in plain words. Null when the row has figures."
          },
          "area": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RentArea"
              },
              {
                "type": "null"
              }
            ],
            "description": "The area the figures describe."
          },
          "location": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RentLocation"
              },
              {
                "type": "null"
              }
            ],
            "description": "Where an address or point was placed. Null for other places."
          },
          "rents": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/RentFigure"
            },
            "description": "One entry per bedroom count, studio to 4 bedrooms. Dollars a month, to the nearest $10."
          },
          "yearly_growth_percent": {
            "type": [
              "number",
              "null"
            ],
            "description": "Rent growth a year for the area, as a percent number (4.0 means 4%)."
          },
          "fair_market_rent": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RentFairMarketRent"
              },
              {
                "type": "null"
              }
            ],
            "description": "HUD’s fair market rent for the place, by bedroom count, with its fiscal year and the ZIP codes it comes from. Null when the row has no figures."
          }
        }
      },
      "RentResponse": {
        "type": "object",
        "required": [
          "results",
          "rent_checks_used_this_month",
          "rent_checks_left_this_month",
          "rent_checks_per_month",
          "rent_checks_purchased_left",
          "resets_at"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RentRow"
            },
            "description": "One row per place, in the order sent."
          },
          "rent_checks_used_this_month": {
            "type": "integer",
            "description": "Rent checks your account has used this month."
          },
          "rent_checks_left_this_month": {
            "type": "integer",
            "description": "Rent checks left this month."
          },
          "rent_checks_per_month": {
            "type": "integer",
            "description": "Your plan’s rent checks a month."
          },
          "rent_checks_purchased_left": {
            "type": "integer",
            "description": "Rent checks bought in packs and not yet spent. Used once this month’s rent checks are gone; they carry over while your account is open."
          },
          "resets_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the count resets: midnight Eastern time on the 1st."
          }
        }
      }
    }
  }
}
