Getting property details

Once you have the Reonomy IDs for properties of interest (see Searching for properties), the API supports multiple ways to obtain information about those properties:

# of properties	Use	See
One per request	GET /property/{id}	Individual properties
Up to 250 per request	POST /property/bulk	Multiple properties
Large quantities	Bulk data feeds	About bulk data feeds

Rate limiting

Requests to GET /v2/property/{property_id} are rate limited to 5 requests per second. Requests to POST /v2/property/bulk are limited to 2 requests per second and 20 requests per minute.

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.

Individual properties

Basic property information

GET /property/{property_id}

This endpoint takes a Reonomy property ID and returns basic information about the property. See Searching for properties to learn how to obtain the ID for a specific property.

Response

For information about the attributes returned in the response, click any highlighted attribute name in the example, or see the response definition for GET /property/{property_id} for a full list.

Note that this example includes several attributes that are only available for New York City properties (block_id, borough_id, etc.). Those attributes are marked NYC properties only in the description.

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.

Property detail information

GET /property/{property_id}?detail_type=<type>

The detail_type query parameter lets you request detail information (mortgages, taxes, etc.) for the specified property. If you omit the parameter, the API returns basic property information.

Note: You can specify multiple instances of this parameter in the query string, as shown in the example.

Response

The response includes information for the detail types specified using the detail_type query parameter, or basic information if you didn't use the parameter in the request.

For information about the attributes returned in the response, click any highlighted attribute name in the example, or see the response definition for GET /property/{property_id}.

Excluding personally identifiable information (PII)

Personally identifiable information (PII) is data that may be used to identify a particular person, and includes names, addresses, emails, etc. Some Reonomy property detail types include PII, and the Data dictionary identifies which fields may contain PII. For example, mortgage data includes the borrower name, the lender name, and the mortgage signatory information, and these are tagged as PII.

PII is included by default, but if you want to exclude it from the API response, you can do so using the filter_pii query parameter, as shown in the example.

Response

The example shows that setting filter_pii to true excludes fields tagged as PII from the response. If you've entered your API access token, you can set filter_pii to false above and run the request to see the PII fields.

Multiple properties

POST /property/bulk

This endpoint takes up to 250 Reonomy property IDs and returns information about the specified properties. See Searching for properties to learn how to obtain IDs for properties that match certain search criteria.

You can request as many of the available property detail types as you want (basic, mortgages, etc.). You can also specify whether you want to exclude personally identifiable information (PII).

Rate limiting

Requests to POST /v2/property/bulk are rate limited at:

2 requests per second
20 requests per minute

To download large quantities of property data, use bulk data feeds.

Response

The reponse is a list with one item per property ID. For information about the attributes returned in the response, click any highlighted attribute name in the example, or see the response definition for POST /property/bulk for a full list.

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.

Obtaining ownership information

The ownership detail type returns information about property ownership that includes the likely owners and their contact information (addresses, emails, and phone numbers).

GET /v2/property/{property_id}	POST /v2/property/bulk
Specify the property's Reonomy ID as the path parameter	Specify the property's Reonomy ID in the `property_ids` request body parameter
Set the `detail_type` query parameter to `ownership`	Set the `detail_type` request body parameter to `ownership`

Response

The response contains a contacts array with contact information for some or all of the following:

The mortgage signatory: This is the person who signed the most recent mortgage (always an individual).
The reported owners: These can be companies or individuals.
Companies linked to the reported owners: For each reported owner name, we attempt to find a matching company, as well as any parent company, within our database of companies. The response includes any available information (headcount, sales volume, etc.) for each company.

The structure of the response is described below. For information about individual attributes, click any highlighted attribute name in the example, or see the response definition in GET /v2/property/{property_id} for a full list.

Unpacking the response

In the API response, each object in the contacts array (there are two in this example) represents an individual or a company with connections to the property:

For contact_type: "individual", the object includes a persons list with a single object containing the person's name and contact information.
For contact_type: "company", the object includes a persons list that may include one or more objects representing individuals associated with the company, along with their contact information.

In addition to the persons list and the contact_type, each object includes the following attributes:

is_signatory: true if the person is the mortgage signatory (the signer of the most recent mortgage on the property). The signatory is always an individual (not a company).
match_score: Indicates the confidence that this is the true owner and determines the order in which contacts are listed. The mortgage signatory always receives a match_score of 101 and is always the first contact in the list.
is_green_match: true for items where the match_score is greater than 50. Unlike the web app, the API does not return "gray" matches, so all contacts in the API response will have is_green_match: true.
company ( for contact_type: "company" only): Includes any available information (headcount, sales volume, etc.), as well as the parent_id if there's a known parent company. If there is a known parent company, it is included as a separate object in the contacts array.

For each person in the persons list, the API response specifies:

The person's name (display is the first_name and last_name combined)
The person's job title(s).
The person's contact information, including addresses, emails, and phone numbers where available
Any websites linked to the person

Expand the nodes in the treeview on the right to see the fields for each information category.

Determining the owner company hierarchy

For contact_type: "company", the company node includes any available information (headcount, sales volume, etc.), as well as a parent_id if there's a known parent company. If there is, the parent company is included as a separate object in the contacts array. Similarly, if the parent company has a known parent company, we include its parent_id, etc. You can use these IDs to determine the ownership hierarchy.

The example shows a property with two contact_type: "company" objects in the contacts array:

If you look at the company node for array item 1, you can see a parent_id listed (37928b1f-5bc1-5355-8496-17e0274d81fe).
If you look at the company node for array item 2, you can see its id is 37928b1f-5bc1-5355-8496-17e0274d81fe, so we know it's the parent of the first company.

Flattening the response

The API response is designed to be machine readable, not human readable. Depending on your use case, you may need to extract the fields of interest from the JSON response and create a flatter, more accessible format.

The sample code shows how you might do this in Python or Javascript. Follow a similar pattern for other languages. If you've entered your API access token (click the Access Token button at the top right), you can enter a Reonomy property ID below and click the ► RUN button to see a table generated from the response using the sample code.

contacts = []
for group in response['contacts']:
  company = group['company']['name'] if 'company' in group else ''
  is_signatory = group['is_signatory']
  match_score = group['match_score']
  for person in group['persons']:
    # Construct an 'addresses' string from its components
    addresses = [
      f"{address['line1']}, {address['city']}, "
      f"{address['state_code']} {address['postal_code']}"
      for address in person['addresses']
    ] 
    # Build a 'contact' object from the response data
    contact = {
        'name': person['display'],
        'match_score': match_score,
        'is_signatory': is_signatory,
        'company': company,
        'job_title': '; '.join([job['title'] for job in person['jobs']]),
        'addresses': '; '.join(addresses),
        'phones': '; '.join([phone['number'] for phone in person['phones']]),
        'emails': '; '.join([email['address'] for email in person['emails']]),
    }
    contacts.append(contact)

Enter a Reonomy property ID and click the ► RUN button to run your request against the Reonomy API.

Response

Parcel shape information

The POST /v2/search/property-shapes endpoint returns the shape files for one or more parcel shape IDs (returned by GET /v2/properties/{id}), or for all parcels contained within or intersecting with the specified bounding box (the red rectangle in the example).

Each shape file that's returned includes the geometry and properties of the specified parcel, including the street address. The geometry specifies a list of coordinate pairs defining the vertices of the parcel according to the GeoJSON specification.

For more information, see POST /search/property-shapes (requires a valid API access token to view).

Return to reonomy.com