Skip to navigation
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 stringsOptional

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.

latdoubleOptional18-72
The property's latitude
londoubleOptional-180--66
The property's longitude
number_unitsdouble or nullOptional

The property’s advertised number_units

year_builtdouble or nullOptional

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

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

When it’s a custom property, this field will be populated with the user_id of the user who created the property.

Errors

400
Bad Request Error