{ "openapi": "3.1.0", "info": { "title": "Realie Property Data API (v3)", "description": "API for looking up property details by address and unit number.", "version": "3.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\" \u2014 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 \u2014 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. \u201c123 Main Street\u201d). 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. \u201cAPT 2B\u201d would just be \u201c2B\u201d)" }, { "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 \"cursor=start\" on the first request to begin a cursor walk, then pass the value from the previous response's \"metadata.nextCursor\" to retrieve each next page. Omitting \"cursor\" entirely returns the legacy offset shape. Constant-time per page regardless of pagination depth \u2014 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 \u2014 \"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 - Billing, card verification, subscription status, or overage spending cap blocks access. Follow action before retrying. The first blocking condition is returned; a non-active subscription can return subscription_inactive before unpaid_invoices. See https://docs.realie.ai/api-reference/response-codes#resolving-a-403-response for each code and recovery steps.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "action", "billing_url" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Use code instead of matching this text in integrations.", "example": "Forbidden: Pay your outstanding invoices to restore access" }, "code": { "type": "string", "description": "Machine-readable reason for the access denial.", "enum": [ "card_not_verified", "payment_method_required", "overage_limit_exceeded", "unpaid_invoices", "subscription_inactive", "subscription_required", "subscription_ended", "billing_unavailable", "billing_configuration_error", "access_denied" ], "example": "unpaid_invoices" }, "action": { "type": "string", "description": "The next step to restore access. Display this guidance to the person who manages billing.", "example": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active." }, "billing_url": { "type": "string", "format": "uri", "description": "Billing page where the account owner can resolve the issue.", "example": "https://app.realie.ai/billing" } } }, "example": { "error": "Forbidden: Pay your outstanding invoices to restore access", "code": "unpaid_invoices", "action": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active.", "billing_url": "https://app.realie.ai/billing" } } } }, "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. \u201cCA\u201d) where the property is located." }, { "name": "address", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The street address line 1 only (e.g. \u201c123 Main Street\u201d). 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. \u201cAPT 2B\u201d would just be \u201c2B\u201d)" }, { "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 - Billing, card verification, subscription status, or overage spending cap blocks access. Follow action before retrying. The first blocking condition is returned; a non-active subscription can return subscription_inactive before unpaid_invoices. See https://docs.realie.ai/api-reference/response-codes#resolving-a-403-response for each code and recovery steps.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "action", "billing_url" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Use code instead of matching this text in integrations.", "example": "Forbidden: Pay your outstanding invoices to restore access" }, "code": { "type": "string", "description": "Machine-readable reason for the access denial.", "enum": [ "card_not_verified", "payment_method_required", "overage_limit_exceeded", "unpaid_invoices", "subscription_inactive", "subscription_required", "subscription_ended", "billing_unavailable", "billing_configuration_error", "access_denied" ], "example": "unpaid_invoices" }, "action": { "type": "string", "description": "The next step to restore access. Display this guidance to the person who manages billing.", "example": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active." }, "billing_url": { "type": "string", "format": "uri", "description": "Billing page where the account owner can resolve the issue.", "example": "https://app.realie.ai/billing" } } }, "example": { "error": "Forbidden: Pay your outstanding invoices to restore access", "code": "unpaid_invoices", "action": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active.", "billing_url": "https://app.realie.ai/billing" } } } }, "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", "description": "Get a single property by its parcel identifier. Pass the assessor's parcel ID (APN) with \"state\" and \"county\", or pass a stored \"realieParcelId\", which also works on its own. When \"state\" or \"county\" is omitted, \"parcelId\" is interpreted only as a realieParcelId: a value that is not a valid realieParcelId returns 400, and if you pass just one of \"state\" or \"county\", it must match the realieParcelId's county or the request returns 400. You can also pass \"realieId\" (the \"realieId\" field of a v3 result) instead of \"parcelId\"; \"state\" and \"county\" are then ignored, and the lookup reads v3 data only.", "operationId": "parcelIdLookup", "tags": [ "Property" ], "x-mint": { "mcp": { "enabled": true, "name": "parcel-id-lookup", "description": "Get a single property by exact Parcel ID (with state and county), by realieParcelId alone, or by realieId alone." } }, "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The state (e.g. CA) where the property is located. Required unless \"parcelId\" is a realieParcelId or \"realieId\" is passed (ignored with \"realieId\")." }, { "name": "county", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The county where the property is located. Required unless \"parcelId\" is a realieParcelId or \"realieId\" is passed (ignored with \"realieId\")." }, { "name": "parcelId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The parcel to look up: the exact assessor's parcel ID (APN), which requires \"state\" and \"county\", or a stored \"realieParcelId\" (the 5-digit county FIPS code, a hyphen, then the APN with spaces written as \"~\", e.g. \"11001-0314-~-0009\"). When \"state\" or \"county\" is omitted, the value is interpreted only as a realieParcelId. Required unless \"realieId\" is passed; do not pass both." }, { "name": "realieId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The \"realieId\" field of a v3 result: 24 hexadecimal characters, e.g. \"6650f1c2a1b2c3d4e5f60718\". Pass it instead of \"parcelId\"; \"state\" and \"county\" are not needed. Reads v3 data only." } ], "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. Returned when neither \"parcelId\" nor \"realieId\" is passed; when \"state\" or \"county\" is omitted and \"parcelId\" is not a valid realieParcelId; when only one of \"state\" or \"county\" is passed and it does not match the realieParcelId's county; when lookup by realieParcelId alone is not available for your account (pass \"state\" and \"county\" instead); when \"realieId\" is not 24 hexadecimal characters or is passed together with \"parcelId\"; or when lookup by realieId is not available for your account or for the parcel's state (pass \"parcelId\" with \"state\" and \"county\" instead).", "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 unless parcelId is a realieParcelId ({5-digit county FIPS}-{APN}), which may be passed alone" } } } } } }, "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 - Billing, card verification, subscription status, or overage spending cap blocks access. Follow action before retrying. The first blocking condition is returned; a non-active subscription can return subscription_inactive before unpaid_invoices. See https://docs.realie.ai/api-reference/response-codes#resolving-a-403-response for each code and recovery steps.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "action", "billing_url" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Use code instead of matching this text in integrations.", "example": "Forbidden: Pay your outstanding invoices to restore access" }, "code": { "type": "string", "description": "Machine-readable reason for the access denial.", "enum": [ "card_not_verified", "payment_method_required", "overage_limit_exceeded", "unpaid_invoices", "subscription_inactive", "subscription_required", "subscription_ended", "billing_unavailable", "billing_configuration_error", "access_denied" ], "example": "unpaid_invoices" }, "action": { "type": "string", "description": "The next step to restore access. Display this guidance to the person who manages billing.", "example": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active." }, "billing_url": { "type": "string", "format": "uri", "description": "Billing page where the account owner can resolve the issue.", "example": "https://app.realie.ai/billing" } } }, "example": { "error": "Forbidden: Pay your outstanding invoices to restore access", "code": "unpaid_invoices", "action": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active.", "billing_url": "https://app.realie.ai/billing" } } } }, "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/owner/": { "get": { "summary": "Owner Search", "description": "Search parcels by recorded current-owner name. Requires state and at least one of lastName or nameContains. Both recorded owner-name slots are searched. The v3 result window is limited to 200 candidate parcels, so broad names can return an incomplete set; refine the query to narrow the results. Pagination uses limit and offset, with offset + limit at most 200 on v3 reads. The account response-shape setting controls whether properties contain nested v3 records or the v2-compatible flat layout; see the [v3 overview](/api-reference/v3/overview) and [Property Data Schema](/api-reference/v3/property-data-schema). Send the API key directly in the Authorization header. Normal API-access and billing checks apply. A successful 200 response costs one token; 400, 401, 403, and 404 responses are not billed. See [Plans and Pricing](/api-reference/pricing). This base endpoint allows up to 100 properties per page. For county filtering, use [Premium Owner Search](/api-reference/v3/premium/premium-owner-search).", "operationId": "ownerSearch", "tags": [ "Property" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two-letter state abbreviation (for example, CA)." }, { "name": "lastName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Owner surname or company name. Required unless nameContains is provided. Matching is case-insensitive. If both lastName and nameContains are supplied, both must match the same recorded owner name." }, { "name": "firstName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional given-name prefix, used with lastName to narrow the owner match." }, { "name": "nameContains", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Match every supplied word in the same recorded owner name; word order does not matter. This is word matching, not an arbitrary substring search. Can be used without lastName. Supported only on v3 data reads; otherwise returns 400." }, { "name": "fuzzy", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Set true to allow one edit with the first two characters matching exactly. Use a single-token lastName for fuzzy surname matching, or nameContains for multiword fuzzy queries. firstName remains a prefix match. Supported only on v3 data reads; otherwise returns 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Maximum results per page. Defaults to 10; values above 100 are capped at 100. On v3 reads, offset + the applied limit must be at most 200 or the request returns 400." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of matched records to skip. Defaults to 0. On v3 reads, offset + the applied limit must be at most 200. Refine the name query rather than paging beyond this window; cursor pagination is not supported." }, { "name": "includeExplicitNulls", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Set true to include missing public nested property fields as explicit nulls. Requires an account enabled for the nested v3 response shape and a v3 data read; otherwise returns 400. Without this flag, fields with unknown values may be omitted." } ], "responses": { "200": { "description": "Matching properties found. Each successful request consumes one token, independent of the number of properties returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "properties", "metadata" ], "properties": { "properties": { "type": "array", "description": "Matching current-owner parcels. Accounts enabled for the v3 response shape receive nested property records on v3 reads; other accounts receive the v2-compatible flat shape. See the v3 Property Data Schema for nested fields.", "items": { "type": "object" } }, "metadata": { "type": "object", "required": [ "limit", "offset", "count" ], "properties": { "limit": { "type": "integer", "description": "Applied page size after defaulting or capping." }, "offset": { "type": "integer", "description": "Applied number of matched records skipped." }, "count": { "type": "integer", "description": "Number of properties in this response, not a total match count." } } } } } } } }, "400": { "description": "Bad Request - Missing state or both name parameters, a v3-only mode used on a v2 read, or offset + limit exceeding 200 on a v3 read. Also returned when includeExplicitNulls=true cannot use the nested v3 response shape.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Description of the error that occurred.", "example": "Bad Request: State and lastName (or nameContains) 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 - Billing, card verification, subscription status, or overage spending cap blocks access. Follow action before retrying. The first blocking condition is returned; a non-active subscription can return subscription_inactive before unpaid_invoices. See https://docs.realie.ai/api-reference/response-codes#resolving-a-403-response for each code and recovery steps.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "action", "billing_url" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Use code instead of matching this text in integrations.", "example": "Forbidden: Pay your outstanding invoices to restore access" }, "code": { "type": "string", "description": "Machine-readable reason for the access denial.", "enum": [ "card_not_verified", "payment_method_required", "overage_limit_exceeded", "unpaid_invoices", "subscription_inactive", "subscription_required", "subscription_ended", "billing_unavailable", "billing_configuration_error", "access_denied" ], "example": "unpaid_invoices" }, "action": { "type": "string", "description": "The next step to restore access. Display this guidance to the person who manages billing.", "example": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active." }, "billing_url": { "type": "string", "format": "uri", "description": "Billing page where the account owner can resolve the issue.", "example": "https://app.realie.ai/billing" } } }, "example": { "error": "Forbidden: Pay your outstanding invoices to restore access", "code": "unpaid_invoices", "action": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active.", "billing_url": "https://app.realie.ai/billing" } } } }, "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" } } } } } }, "503": { "description": "Service temporarily unavailable, including a database timeout. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "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 - Billing, card verification, subscription status, or overage spending cap blocks access. Follow action before retrying. The first blocking condition is returned; a non-active subscription can return subscription_inactive before unpaid_invoices. See https://docs.realie.ai/api-reference/response-codes#resolving-a-403-response for each code and recovery steps.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "action", "billing_url" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Use code instead of matching this text in integrations.", "example": "Forbidden: Pay your outstanding invoices to restore access" }, "code": { "type": "string", "description": "Machine-readable reason for the access denial.", "enum": [ "card_not_verified", "payment_method_required", "overage_limit_exceeded", "unpaid_invoices", "subscription_inactive", "subscription_required", "subscription_ended", "billing_unavailable", "billing_configuration_error", "access_denied" ], "example": "unpaid_invoices" }, "action": { "type": "string", "description": "The next step to restore access. Display this guidance to the person who manages billing.", "example": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active." }, "billing_url": { "type": "string", "format": "uri", "description": "Billing page where the account owner can resolve the issue.", "example": "https://app.realie.ai/billing" } } }, "example": { "error": "Forbidden: Pay your outstanding invoices to restore access", "code": "unpaid_invoices", "action": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active.", "billing_url": "https://app.realie.ai/billing" } } } }, "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/owner/": { "get": { "summary": "Premium Owner Search", "description": "Search parcels by recorded current-owner name. Requires state and at least one of lastName or nameContains. Both recorded owner-name slots are searched. The v3 result window is limited to 200 candidate parcels, so broad names can return an incomplete set; refine the query to narrow the results. Pagination uses limit and offset, with offset + limit at most 200 on v3 reads. The account response-shape setting controls whether properties contain nested v3 records or the v2-compatible flat layout; see the [v3 overview](/api-reference/v3/overview) and [Property Data Schema](/api-reference/v3/property-data-schema). Send the API key directly in the Authorization header. Normal API-access and billing checks apply. A successful 200 response costs one token; 400, 401, 403, and 404 responses are not billed. See [Plans and Pricing](/api-reference/pricing). This premium endpoint uses the same name-matching engine as [Owner Search](/api-reference/v3/property/owner-search), adds optional county filtering, and caps each page at 25 properties.", "operationId": "premiumOwnerSearch", "tags": [ "Premium" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two-letter state abbreviation (for example, CA)." }, { "name": "lastName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Owner surname or company name. Required unless nameContains is provided. Matching is case-insensitive. If both lastName and nameContains are supplied, both must match the same recorded owner name." }, { "name": "firstName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional given-name prefix, used with lastName to narrow the owner match." }, { "name": "county", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional county name within the state. An unrecognized county returns 404 (no properties found)." }, { "name": "nameContains", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Match every supplied word in the same recorded owner name; word order does not matter. This is word matching, not an arbitrary substring search. Can be used without lastName. Supported only on v3 data reads; otherwise returns 400." }, { "name": "fuzzy", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Set true to allow one edit with the first two characters matching exactly. Use a single-token lastName for fuzzy surname matching, or nameContains for multiword fuzzy queries. firstName remains a prefix match. Supported only on v3 data reads; otherwise returns 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 }, "description": "Maximum results per page. Defaults to 10; values above 25 are capped at 25. On v3 reads, offset + the applied limit must be at most 200 or the request returns 400." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of matched records to skip. Defaults to 0. On v3 reads, offset + the applied limit must be at most 200. Refine the name query rather than paging beyond this window; cursor pagination is not supported." } ], "responses": { "200": { "description": "Matching properties found. Each successful request consumes one token, independent of the number of properties returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "properties", "metadata" ], "properties": { "properties": { "type": "array", "description": "Matching current-owner parcels. Accounts enabled for the v3 response shape receive nested property records on v3 reads; other accounts receive the v2-compatible flat shape. See the v3 Property Data Schema for nested fields.", "items": { "type": "object" } }, "metadata": { "type": "object", "required": [ "limit", "offset", "count" ], "properties": { "limit": { "type": "integer", "description": "Applied page size after defaulting or capping." }, "offset": { "type": "integer", "description": "Applied number of matched records skipped." }, "count": { "type": "integer", "description": "Number of properties in this response, not a total match count." } } } } } } } }, "400": { "description": "Bad Request - Missing state or both name parameters, a v3-only mode used on a v2 read, or offset + limit exceeding 200 on a v3 read.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Description of the error that occurred.", "example": "Bad Request: State and lastName (or nameContains) 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 - Billing, card verification, subscription status, or overage spending cap blocks access. Follow action before retrying. The first blocking condition is returned; a non-active subscription can return subscription_inactive before unpaid_invoices. See https://docs.realie.ai/api-reference/response-codes#resolving-a-403-response for each code and recovery steps.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "action", "billing_url" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Use code instead of matching this text in integrations.", "example": "Forbidden: Pay your outstanding invoices to restore access" }, "code": { "type": "string", "description": "Machine-readable reason for the access denial.", "enum": [ "card_not_verified", "payment_method_required", "overage_limit_exceeded", "unpaid_invoices", "subscription_inactive", "subscription_required", "subscription_ended", "billing_unavailable", "billing_configuration_error", "access_denied" ], "example": "unpaid_invoices" }, "action": { "type": "string", "description": "The next step to restore access. Display this guidance to the person who manages billing.", "example": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active." }, "billing_url": { "type": "string", "format": "uri", "description": "Billing page where the account owner can resolve the issue.", "example": "https://app.realie.ai/billing" } } }, "example": { "error": "Forbidden: Pay your outstanding invoices to restore access", "code": "unpaid_invoices", "action": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active.", "billing_url": "https://app.realie.ai/billing" } } } }, "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" } } } } } }, "503": { "description": "Service temporarily unavailable, including a database timeout. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/public/premium/comparables/": { "get": { "summary": "Premium Comparables Search", "description": "Search for comparable properties based on location and optional property characteristics. Set \"full=true\" to also return each comparable's full property record.", "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." }, { "name": "full", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "If true, each comparable also carries a \"property\" object with the comparable's full property record (for example year built, lot size, and pool), in the same response shape your account receives from Parcel ID Lookup. The comparables returned, their order, the filters, and the token cost are unchanged, but responses are much larger. Defaults to false." } ], "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", "description": "One comparable. \"transferPrice\" and \"transferDateObject\" on the comparable describe its qualifying sale.", "properties": { "property": { "type": "object", "description": "Present only when \"full=true\". The comparable's full property record, in the same shape your account receives from [Parcel ID Lookup](/api-reference/v3/property/parcel-id-lookup): the nested v3 record ([Property Data Schema (v3)](/api-reference/v3/property-data-schema)) for accounts on the v3 response shape, or the v2-compatible flat record ([legacy schema](/api-reference/property-data-schema)) otherwise. Sale fields inside this record come from the parcel's own sales record (in the flat shape, \"transferPrice\" and \"transferDate\" are its most recent sale), so they can differ from the comparable's qualifying sale." } } } }, "metadata": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of comparable properties found" }, "searchParams": { "type": "object", "description": "Parameters used in the search" }, "full": { "type": "boolean", "description": "Present, and true, only when the request set \"full=true\"." } } } } } } } }, "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 - Billing, card verification, subscription status, or overage spending cap blocks access. Follow action before retrying. The first blocking condition is returned; a non-active subscription can return subscription_inactive before unpaid_invoices. See https://docs.realie.ai/api-reference/response-codes#resolving-a-403-response for each code and recovery steps.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "action", "billing_url" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Use code instead of matching this text in integrations.", "example": "Forbidden: Pay your outstanding invoices to restore access" }, "code": { "type": "string", "description": "Machine-readable reason for the access denial.", "enum": [ "card_not_verified", "payment_method_required", "overage_limit_exceeded", "unpaid_invoices", "subscription_inactive", "subscription_required", "subscription_ended", "billing_unavailable", "billing_configuration_error", "access_denied" ], "example": "unpaid_invoices" }, "action": { "type": "string", "description": "The next step to restore access. Display this guidance to the person who manages billing.", "example": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active." }, "billing_url": { "type": "string", "format": "uri", "description": "Billing page where the account owner can resolve the issue.", "example": "https://app.realie.ai/billing" } } }, "example": { "error": "Forbidden: Pay your outstanding invoices to restore access", "code": "unpaid_invoices", "action": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active.", "billing_url": "https://app.realie.ai/billing" } } } }, "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." } } } }