{
  "openapi": "3.1.0",
  "info": {
    "title": "Property Data API",
    "description": "API for looking up property details by address and unit number.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://app.realie.ai/api"
    }
  ],
  "paths": {
    "/public/property/search/": {
      "get": {
        "summary": "Property Search",
        "description": "Search and paginate through properties across states, counties, or cities. The \"state\" field is required. For best performance and lowest latency, include \"state\", \"county\", and \"address\" — ZIP codes and city names vary across data sources. By default, broad searches exclude parcels without assigned addresses; set \"includeUnassignedAddress=true\" to include them. **Pagination:** use the \"cursor\" parameter for efficient pagination at any depth — see the [Pagination guide](/api-reference/pagination) for full details. The legacy \"offset\" parameter still works but is deprecated.",
        "operationId": "propertySearch",
        "tags": [
          "Property"
        ],
        "x-mint": {
          "mcp": {
            "enabled": true,
            "name": "property-search",
            "description": "Search or paginate properties"
          }
        },
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Two-letter state (required field) (e.g., \"CA\")",
            "example": "DC"
          },
          {
            "name": "zipCode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ZIP code of the property (optional field).",
            "example": "20009"
          },
          {
            "name": "county",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "County where the property is located (optional field).",
            "example": "MONTEREY"
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "City where the property is located (optional field).",
            "example": "CARMEL"
          },
          {
            "name": "transferedSince",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Days to look back for transfers (e.g., \"30\") (optional field)."
          },
          {
            "name": "useCode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Numerical use code (e.g., 1002, 1001) (optional field)."
          },
          {
            "name": "address",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The street address line 1 only (e.g. “123 Main Street”). Do not include city, state, or ZIP in this field. (optional field)",
            "example": "2022 R ST NW"
          },
          {
            "name": "unitNumberStripped",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The unit number of the property (optional field). Do not include the type of unit. (e.g. “APT 2B” would just be “2B”)"
          },
          {
            "name": "includeUnassignedAddress",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "If true, include parcels that do not yet have an assigned address. By default, broad searches exclude null or blank addresses."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            },
            "description": "Maximum number of results to return. Defaults to 10, maximum is 100.",
            "example": 10
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Opaque pagination token. Pass the value from a previous response's \"metadata.nextCursor\" to retrieve the next page. Omit on the first request. Constant-time per page regardless of pagination depth — preferred over \"offset\" for paginating through more than a few hundred results."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "deprecated": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "**Deprecated.** Number of records to skip. Defaults to 0. Use \"cursor\" instead — \"offset\" does not scale beyond a few thousand records and may produce timeout errors on deep pagination. Responses that include the \"offset\" parameter will return a \"Deprecation: true\" header along with a \"metadata.deprecationNotice\" field.",
            "example": 0
          },
          {
            "name": "residential",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "If true, only residential properties; if false, only non-residential (optional field)."
          }
        ],
        "responses": {
          "200": {
            "description": "Properties found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "properties": {
                      "type": "array",
                      "description": "Array of property features found.",
                      "items": {
                        "type": "object"
                      }
                    },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "description": "Limit applied"
                        },
                        "count": {
                          "type": "integer",
                          "description": "Number of records returned in this page"
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Cursor pagination only. Pass this value as \"cursor\" on the next request to retrieve the next page. Null when there are no more results."
                        },
                        "offset": {
                          "type": "integer",
                          "deprecated": true,
                          "description": "Offset pagination only (deprecated). Echoes the offset value used for this request."
                        },
                        "deprecationNotice": {
                          "type": "string",
                          "description": "Present only when a deprecated parameter (e.g., \"offset\") was used. Human-readable migration message."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Missing or invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Please include state."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Unauthorized: API key is missing"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Usage limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Forbidden: Usage limit exceeded"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found - No properties found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "No properties found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "apiKeyAuth": []
          }
        ]
      }
    },
    "/public/property/address/": {
      "get": {
        "summary": "Address Lookup",
        "operationId": "addressLookup",
        "tags": [
          "Property"
        ],
        "x-mint": {
          "mcp": {
            "enabled": true,
            "name": "address-lookup",
            "description": "Get a single property by exact address (+optional unit)."
          }
        },
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The state (e.g. “CA”) where the property is located."
          },
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The street address line 1 only (e.g. “123 Main Street”). Do not include city, state, or ZIP in this field."
          },
          {
            "name": "unitNumberStripped",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The unit number of the property (optional). Do not include the type of unit. (e.g. “APT 2B” would just be “2B”)"
          },
          {
            "name": "county",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The county where the property is located. Required when city parameter is provided."
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The city where the property is located. If specified, county parameter is required."
          }
        ],
        "responses": {
          "200": {
            "description": "Property found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "property": {
                      "type": "object",
                      "description": "The property features found."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Missing or invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Bad Request: Both address and state are required parameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Unauthorized: API key is missing"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Usage limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Forbidden: Usage limit exceeded"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found - Address not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Address not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "apiKeyAuth": []
          }
        ]
      }
    },
    "/public/property/parcelId/": {
      "get": {
        "summary": "Parcel ID Lookup",
        "operationId": "parcelIdLookup",
        "tags": [
          "Property"
        ],
        "x-mint": {
          "mcp": {
            "enabled": true,
            "name": "parcel-id-lookup",
            "description": "Get a single property by exact Parcel ID."
          }
        },
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The state (e.g. CA) where the property is located."
          },
          {
            "name": "county",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The county where the property is located."
          },
          {
            "name": "parcelId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The exact parcel ID to lookup."
          }
        ],
        "responses": {
          "200": {
            "description": "Property found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "property": {
                      "type": "object",
                      "description": "The property features found."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Missing or invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "State, county, and parcelId are all required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Unauthorized: API key is missing"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Usage limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Forbidden: Usage limit exceeded"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found - No property found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "No property found matching the criteria"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "apiKeyAuth": []
          }
        ]
      }
    },
    "/public/property/location/": {
      "get": {
        "summary": "Location Search",
        "description": "Search by latitude/longitude with an optional radius in miles. By default, nearby searches exclude parcels without assigned addresses unless you explicitly set `includeUnassignedAddress=true`.",
        "operationId": "locationSearch",
        "tags": [
          "Property"
        ],
        "x-mint": {
          "mcp": {
            "enabled": true,
            "name": "location-search",
            "description": "Search by latitude/longitude with an optional radius (miles). Query parameters only; no request body."
          }
        },
        "parameters": [
          {
            "name": "longitude",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "format": "float"
            },
            "description": "The longitude coordinate of the center point for the search."
          },
          {
            "name": "latitude",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "format": "float"
            },
            "description": "The latitude coordinate of the center point for the search."
          },
          {
            "name": "radius",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "format": "float",
              "minimum": 0,
              "maximum": 2,
              "default": 1
            },
            "description": "The radius in miles to search from the center point. Maximum value is 2 miles."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            },
            "description": "Maximum number of results to return. Defaults to 10, maximum is 100."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Number of records to skip. Defaults to 0."
          },
          {
            "name": "residential",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Filter for residential properties only. If true, returns only residential properties. If false, returns only non-residential properties."
          },
          {
            "name": "includeUnassignedAddress",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "If true, include nearby parcels that do not yet have an assigned address. By default, null or blank addresses are excluded."
          }
        ],
        "responses": {
          "200": {
            "description": "Properties found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "properties": {
                      "type": "array",
                      "description": "Array of properties found within the specified radius.",
                      "items": {
                        "type": "object"
                      }
                    },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "description": "Limit value applied to the request"
                        },
                        "offset": {
                          "type": "integer",
                          "description": "Number of records skipped"
                        },
                        "count": {
                          "type": "integer",
                          "description": "Number of records found"
                        },
                        "searchCenter": {
                          "type": "object",
                          "properties": {
                            "longitude": {
                              "type": "number",
                              "description": "The longitude of the search center point"
                            },
                            "latitude": {
                              "type": "number",
                              "description": "The latitude of the search center point"
                            }
                          }
                        },
                        "radiusMiles": {
                          "type": "number",
                          "description": "The radius in miles used for the search"
                        },
                        "includeUnassignedAddress": {
                          "type": "boolean",
                          "description": "Whether parcels without assigned addresses were included in the search"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Missing or invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Bad Request: longitude, latitude, and radius must be valid numbers"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Unauthorized: API key is missing"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Usage limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Forbidden: Usage limit exceeded"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found - No properties found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "No properties found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "apiKeyAuth": []
          }
        ]
      }
    },
    "/public/premium/comparables/": {
      "get": {
        "summary": "Premium Comparables Search",
        "description": "Search for comparable properties based on location and optional property characteristics.",
        "operationId": "comparableSearch",
        "tags": [
          "Premium"
        ],
        "parameters": [
          {
            "name": "latitude",
            "in": "query",
            "required": true,
            "schema": {
              "type": "float"
            },
            "description": "The latitude coordinate of the target property."
          },
          {
            "name": "longitude",
            "in": "query",
            "required": true,
            "schema": {
              "type": "float"
            },
            "description": "The longitude coordinate of the target property."
          },
          {
            "name": "radius",
            "in": "query",
            "required": false,
            "schema": {
              "type": "float",
              "default": 1
            },
            "description": "Search radius in miles. Defaults to 1 mile."
          },
          {
            "name": "timeFrame",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 18
            },
            "description": "Number of months to look back for comparable sales. Defaults to 18 months."
          },
          {
            "name": "maxResults",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 25
            },
            "description": "Maximum number of results to return. Defaults to 25, maximum is 50."
          },
          {
            "name": "sqftMin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Minimum square footage."
          },
          {
            "name": "sqftMax",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Maximum square footage."
          },
          {
            "name": "bedsMin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Minimum number of bedrooms."
          },
          {
            "name": "bedsMax",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Maximum number of bedrooms."
          },
          {
            "name": "bathsMin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "float"
            },
            "description": "Minimum number of bathrooms."
          },
          {
            "name": "bathsMax",
            "in": "query",
            "required": false,
            "schema": {
              "type": "float"
            },
            "description": "Maximum number of bathrooms."
          },
          {
            "name": "propertyType",
            "in": "query",
            "required": false,
            "schema": {
              "enum": [
                "any",
                "condo",
                "house"
              ]
            },
            "description": "Type of property to search for."
          },
          {
            "name": "priceMin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Minimum price."
          },
          {
            "name": "priceMax",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Maximum price."
          }
        ],
        "responses": {
          "200": {
            "description": "Comparable properties found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "comparables": {
                      "type": "array",
                      "description": "Array of comparable properties found.",
                      "items": {
                        "type": "object"
                      }
                    },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer",
                          "description": "Number of comparable properties found"
                        },
                        "searchParams": {
                          "type": "object",
                          "description": "Parameters used in the search"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Missing or invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Bad Request: latitude and longitude are required parameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Unauthorized: API key is missing"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Usage limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Forbidden: Usage limit exceeded"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found - No comparable properties found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "No comparable properties found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Description of the error that occurred.",
                      "example": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "apiKeyAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header",
        "description": "Provide your API key directly in the header."
      }
    }
  }
}