Property

Search

Search for a property by name, address, or other identifying text. This endpoint matches properties based on a query string. A well-formatted input—such as a full address—is more likely to return accurate results. We also include known aliases and alternate addresses when available. **Important**: This search endpoint only returns properties from HelloData's indexed database. Private properties created via POST /property (custom-created properties) are not indexed and will not appear in search results. The intended workflow is to use this search endpoint to find HelloData property IDs initially, then store those IDs for future direct access. If you create a property via POST /property, store the returned ID and use it directly—do not expect to find it via search. **Recommendation**: Use filters whenever possible to improve performance and result quality. Filtering options: - Use `lat` and `lon` together to sort results by proximity. - Use `max_distance` (in miles) with `lat` and `lon` to limit results to a given radius. - Use `state` (e.g. 'CA') or `zip_code` (5-digit or ZIP+4 formats) to restrict results by region.

Authentication

x-api-keystring
API Key authentication via header
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

qstringRequired
The search query string. Can include a property name, address, id, or partial text.
latdoubleOptional

Latitude for proximity-based sorting. Must be used with lon.

londoubleOptional

Longitude for proximity-based sorting. Must be used with lat.

statestringOptional

Optional. State abbreviation to filter results (e.g. ‘NY’).

zip_codestringOptional

Optional. Zip code to filter results. Accepts 5-digit or ZIP+4 formats; missing leading zeros are automatically handled.

max_distancedoubleOptional

Optional. Maximum distance in miles for nearby results. Requires both lat and lon.

Response

A simplified list of matched properties.
idstringformat: "uuid"
The primary unique identifier of the property. It is a stringified UUIDv5. This value can occasionally change if multiple properties get merged into one.
building_namestring or null
The property's name.
building_name_aliaslist of strings
Other known names for the property. When searching for a property by name, these aliases will also be matched.
street_addressstring
The property's street address part of the full address.
street_address_aliaslist of strings
Other known street addresses for the property. When searching for a property by address, these aliases will also be matched.
citystring
The property's city.
statestring

The property’s state. Formatted as a 2-char string.

zip_codestring

The property’s zip code. Formatted as a 5-char string with leading 0.

id_aliaslist of strings

A list of alternate unique identifiers (alias IDs) for the property. These IDs are typically derived from historical addresses and remain valid even if the primary address changes over time. While old IDs are automatically redirected to the current primary ID, exposing alias IDs helps with deduplication and data consistency.

latdouble18-72
The property's latitude
londouble-180--66
The property's longitude
number_unitsdouble or null

The property’s advertised number_units

year_builtdouble or null

The property’s year_built. This can be in the future if the property is under construction.

number_storiesdouble or null
The property's number of stories.
created_onstringformat: "^\d{4}-\d{2}-\d{2}$"
The date when this record was last updated.

Errors

400
Bad Request Error