Reonomy logo

Technical Documentation

Searching for properties

Before you can retrieve information about a property, you'll need to determine its property ID (also known as the Reonomy ID). The property ID is a unique identifier assigned to each property in the Reonomy database.

There are two endpoints you can use to obtain the IDs for properties of interest:

  • POST /v2/search/summaries (see Filtered search): Use this to search for properties that meet certain criteria (sales_price less than some value, mortgage_origination_date before a specific date, etc.). You can also search for properties within a geocoded region (see Searching by geolocation).

  • POST /v2/resolve/property (see Property resolution): Use this to search for a specific property using its address, geolocation, or place name.

A third endpoint, POST /v2/search/property-shapes, lets you search for parcels contained within, intersecting with, or close to the specified bounding box (see Searching for parcels. This endpoint does not return property IDs, but instead returns the street address and parcel geometry for each match.

Rate limiting

Requests to the search endpoints are rate limited to 5 requests per second.

If you exceed the rate limit for a given time period, the API returns HTTP status code 429 and you must wait before submitting additional requests.

Filtered search

Using the filtered search endpoint

POST https://api.reonomy.com/v2/search/summaries

This endpoint returns the property IDs and coordinates of properties that meet certain criteria, for example, properties in New York City of at least 100,000 square feet. This endpoint is used when you search for properties using the filter options in the Reonomy app.

To use this endpoint, include a settings object in the request body specifying the search parameters, as shown in the example. For a list of all available settings attributes, see POST /search/summaries.

Note: If you want to specify a range (for example, properties between 100,000 and 250,000 square feet), you can specify min and max values.

Response

When you make a request to POST /search/summaries, the response includes:

  • A count of the total number of matching properties
  • An items list with information about each of the first n matching items, including the property ID (id) and the property's latitude and longitude (location). Use the Map tab to see where the properties are located.

By default, you'll get the first 10 matching items. Use the limit attribute in the request body to request up to 10,000 matching items. This example uses "limit": 100.

To request additional matching items beyond the first 10 (or the limit you specified), re-run the request with the search_token as a query parameter. See Pagination below for details.

You can use the id as the path parameter in GET /property/{property_id}, or you can pass a list of IDs to POST /property/bulk to get information about matching properties (see Getting property details for more information). Click the IDs tab to view a list with just the property IDs that you can use with POST /v2/property/bulk.

Importing a web app search

If you use the Reonomy web app, you can import an existing web app search to use as the POST /search/summaries request body:

  1. On the Reonomy web app Search page, select a search from your "Saved Searches" or "Recent Searches."
  2. Copy the URL from the browser address bar.
  3. Paste the URL into the field below. You'll see the search query in the example code on the right.
Response

After importing a web app search, you can run the search query and see the response by clicking the  RUN button in the code example component above.

Pagination

POST /search/summaries returns the first 10 matching items, or the number you requested using the limit parameter (maximum 10,000).

To request additional matching items, re-run the search request but include the search_token returned in the response as a query parameter, as shown in the example.

You can rerun the request with the search token multiple times until you've received all the matching items (the count value in the response).

Note: The search token expires 30 seconds after executing the initial search. The API returns HTTP status code 400 if the search token has expired.

Asset type search example

If you want to search for parcels with specific asset or land use types, the POST /v2/search/summaries endpoint's settings object has attributes you can use to specify these:

  • Use asset_category to specify one or more asset or land use categories.
  • Use land_use_code_description to specify one or more asset or land use types.

You should search using EITHER the broader asset categories OR the narrower land use code descriptions. If you specify a land use category AND a land use code description that isn't related to the asset type you specified, you won't get any results.

  • An asset category is the broad land use category assigned to a parcel.
  • A land use code description is a narrower land use definition.

There are multiple asset or land use types associated with each asset category. See the Asset Types code table to see the relationships.

To try an asset type search, select one or more asset categories or land use code descriptions below. If you want to narrow your search by geography, enter one or more FIPS codes in the fips field. If you've entered your API access token, you can use the  RUN button to run your request against the Reonomy API and see the response.

Response

The default response includes the count of properties that match the search criteria, as well as the property ID and update information for the first 10 items.

If you run the query and get an AuthorizationException, use the Access Token button in the top navigation bar to set your API access token.

Specifying date ranges

Certain fields within thesettings object let you specify date ranges, for example:

  • master_update_time: The last time any of the property data was updated.
  • sale_update_time: The last time sale information was updated
  • foreclosure_aution_date: The foreclosure auction date

For these date fields, there are various ways to specify date ranges:

  • You can specify a min (earliest) date and a max (most recent) date, for example:

    "master_update_time": {
      "min": "1970-01-10",
      "max": "2010-05-01"
    }
    
  • You can specify relative dates using relative_min (earliest) and relative_max (most recent), for example, between 100 days ago and 50 days ago:

    "sale_update_time": {
      "relative_min": -100,
      "relative_max": -50,
    }
    
  • When specifying a range, setting inclusive to false (the default is true) returns properties outside the specified range:

    "mtg_update_time": {
      "inclusive": false,
      "min": "2019-01-01",
      "max": "2019-12-31"
    }
    

Sorting search results

By default, POST /search/summaries returns matching items in an unspecified order. The sort parameter supports a limited set of attributes you can use to sort the search results by assd_total_value, building_area, etc. in ascending or descending order.

The sort parameter takes an array of sort objects, enabling you to sort on multiple fields. For example, you could sort first by year_built and then, within each year, by sales_price.

Click the name field below to see the available sort fields. If you've entered your API access token, click the  RUN button to see how changing the sort and order fields affects the response.

Response

Given the limited information in the POST /search/summaries response, it won't be obvious that the results are sorted. If you extract the resulting property IDs and pass them to POST /v2/property/bulk, you can confirm they are sorted.

Sorting results by location

You can also sort the search results by distance from a specified point. To do this, enter the point's latitude and longitude in the sort parameter's location field. Then select location in the name field. Setting the order to asc will sort the results with the property closest to the specified point first.

Response

Results are returned based on the distance from the specified point.

Searching by geolocation

The API offers various ways to search for properties geolocation:

ObjectGeo search options
PointSearch for properties within a certain distance of a point specified by its geographic coordinates (latitude and longitude).
PolygonSearch for properties within a polygonal shape, using the coordinates of each vertex.
Bounding boxSearch for properties within a rectangular bounding box, specified using the coordinates of the top left and bottom right corners.
Geo shapes

© Mapbox © OpenStreetMap

Search for properties within a radius

The POST /v2/search/summaries endpoint lets you search for properties within a given radius of a point. The example below returns multifamily properties within 100m of the specified point (a location in New York City).

Radius search results

© Mapbox © OpenStreetMap

To try a radius search, select one or more asset_category types, and enter the point coordinates and search radius into the circles fields below. If you've entered your API access token, you can use the  RUN button to run your request against the Reonomy API and see the response.

Response

The POST /v2/search/summaries endpoint returns:

  • A count of the total number of matching properties.
  • An items array with information about each of the first 10 matching items, including the property ID (id).

You can use the id as the path parameter in GET /property/{property_id} to get property data for each matching property. See Getting property details for more information.

Search for properties within a polygon

The POST /v2/search/summaries map_filters attribute also lets you search for properties within one or more polygons, where each polygon is defined by the geographical coordinates of its vertices. The example in this section returns properties within the polygon defined around the northern end of Roosevelt Island in New York City.

For the polygon definitions, the API requires a list of lat/lon coordinate objects for each polygon, as shown in the sample code. However, you may find it easier to define the shapes in GeoJSON using a tool like geojson.io, and then use the paste box below to have the GeoJSON translated into the required format. To do this:

  1. Go to geojson.io.
  2. Zoom in on an area within the United States.
  3. Click the Polygon tool and mark the perimeter of the area.
  4. Repeat for any other polygons you want to include in the search.
  5. Select all of the GeoJSON in the right panel and copy it to the clipboard.
  6. Paste the GeoJSON into the box below.
Draw a polygon
Response

The POST /v2/search/summaries endpoint returns:

  • A count of the total number of matching properties.
  • An items array with information about each of the first 10 matching items, including the property ID (id).

You can use the id as the path parameter in GET /property/{property_id} to get property data for each matching property. See Getting property details for more information.

Search for properties within a bounding box

The POST /v2/search/summaries endpoint also lets you search for properties within a rectangular bounding box, where the bounding box is defined by the geographical coordinates of the top left and bottom right corners, as shown in the sample code.

To try a bounding box search, enter the coordinates of the top left and bottom right corners below. Since the settings object is required, type one or more asset types into the asset_category listbox as well. If you've entered your API access token, you can use the  RUN button to run your request against the Reonomy API and see the response.

Response

The POST /v2/search/summaries endpoint returns:

  • A count of the total number of matching properties.
  • An items array with information about each of the first 10 matching items, including the property ID (id).

You can use the id as the path parameter in GET /property/{property_id} to get property data for each matching property. See Getting property details for more information.

Sorting search results

The sort parameter on the POST /search/summaries endpoint lets you specify how the matching properties are sorted.

Property resolution

POST https://api.reonomy.com/v2/resolve/property

If you have the address, geolocation, or name of a specific property, you can use the POST /v2/resolve/property endpoint to locate a matching Reonomy property ID. This endpoint is used when you search for properties using the address search option in the Reonomy app.

Property resolution credits

Each call to POST /v2/resolve/property uses one property resolution credit. For information on checking credit usage, see API credits.

Bulk property search

If you're searching for property IDs for a large number of properties, you can submit a CSV file with property addresses as a bulk data feed job. See About bulk data feeds for more information.

There are three ways you can search using this endpoint:

  • By address, using the property's street address (as shown in the example).
  • By location, using the property's latitude and longitude.
  • By place, using the property's name (for well known places like the Empire State Building).

You must specify a params object in the request body, and the params object must include an address object, a location object, or a place object. See the following sections for details:

Response

If there's a match, the API returns a params object with the data you provided, plus the following response attributes:

  • property_id: The matching property's Reonomy ID
  • shape_id: Not used
  • status: OK if the search returned a match; PARTIAL or MISS otherwise (see Missing properties)
  • status_code: null if the search returned a match; see Missing properties for other status codes

Searching by address

To search for a property using its street address, specify an address object in the request body's params parameter, as shown in the example. If there are multiple properties at the same address, the API returns the property on the largest parcel. The address object supports the attributes shown below.

Search by location

To search for a property using its latitude/longitude, specify a location object in the request body's params parameter, as shown in the example.

Search by place name

The API lets you locate properties by place name. To search by place name, specify a place object in the request body's params parameter, as shown in the example.

Missing properties

The POST /v2/resolve/property response includes a status and a status_code:

FieldDescription
statusThe match resolution status:
OK: A commercial property was found at the specified address or location.
MISS: No matching commercial property found. See status_code for additional information.
PARTIAL (for address search only): The supplied address was ambiguous. The returned property ID represents the best match available.
status_codeAdditional information (if no match found):
SFR: The property at this address or location is categorized as a single family residence (SFR), therefore no data is available.
Condo Property (SFR): The property at this address or location is categorized as a residential condominium, therefore no data is available.
MISSING: No known property at the supplied address or location.
Unrecognized address: Unable to match the supplied address or location for a reason other than those specified above.
{
  "params": {
    "address": {
      "city": "Chicago",
      "line1": "4502 S Hermitage Ave",
      "state": "IL"
    }
  },
  "property_id": null,
  "shape_id": "1081039213",
  "status": "MISS",
  "status_code": "SFR"
}

Searching for parcels

The POST /search/property-shapes endpoint (requires a valid API access token to view) lets you search for parcels (tax lots) intersecting with or close to the specified bounding box (the red rectangle in the example). The response includes the number of properties, as well as the geometry and properties of each parcel.

Note that the API response does not include the property IDs associated with the parcels. To find property IDs, use one of the other search methods described on this page.

Parcel search

To try a bounding box search, enter the coordinates of the bottom right and top left corners below. The prefilled values define the bounding box shown in the example (a location in New York City), but you can edit these or enter any values you want. If you've entered your API access token, you can use the  RUN button to run your request against the Reonomy API and see the response.

Response

The POST /v2/search/parcel-shapes endpoint returns:

  • A count of the total number of parcels (tax lots) intersecting with or close to the search bounding box.
  • An items array with the GeoJSON geometry definitions for each parcel. By default you get the first 10 items. The limit set for this example is 100.

Within the response, the geometry specifies a list of coordinate pairs defining the vertices of the parcel according to the GeoJSON specification:

  • The GeoJSON tab displays the parcel geometries as a GeoJSON FeatureCollection that includes the search bounding box as the first feature. You can copy and paste the GeoJSON into a tool like geojson.io.
  • The Map tab displays the parcel shapes on a map, with the search bounding box displayed in pink.

Using GeoJSON

The POST /v2/search/property-shapes endpoint (requires a valid API access token to view) takes a list of lat/lon coordinate objects that define the search bounding box, as shown in the example above. However, you may find it easier to define the shape in GeoJSON using a tool like geojson.io, and then translate the definition into the required format. To do this:

  1. Go to geojson.io.
  2. Zoom in to the area of interest within the United States.
  3. Click the Rectangle tool and mark the perimeter of the area.
  4. Select all of the GeoJSON in the right panel and copy it to the clipboard.
  5. Paste the GeoJSON into the box below.
Draw a polygon

© Mapbox © OpenStreetMap

Response

The POST /v2/search/parcel-shapes endpoint returns:

  • A count of the total number of parcels (tax lots) contained by or intersecting with the search bounding box.
  • An items array with the GeoJSON geometry definitions for each parcel. By default you get the first 10 items. The limit set for this example is 100.

The Response tabs on the right include two additional tabs for viewing the API response:

  • The GeoJSON tab displays the parcel geometries as a GeoJSON FeatureCollection that includes the search bounding box as the first feature. You can copy and paste the GeoJSON into a tool like geojson.io.
  • The Map tab displays the parcel shapes on a map, with the search bounding box displayed in pink.

Note that the API response does not include the property IDs associated with the parcels. To find property IDs, use one of the other search methods described on this page.

Copyright © 2022 Reonomy® All rights reserved.

Return to reonomy.com