API Reference

Property Quickstart

Access real-time unit-level data

Property API Quickstart Guide

Welcome to the Parcl Labs Property-Level API Quickstart! This guide will help you get up and running with the Property endpoints, enabling you to access real-time unit-level data that integrates property attributes with sales, listing, and rental events.

If you're an experienced developer and want to jump straight into the code, you can skip this guide and explore our API reference.


Get Started with the Property-Level API

1. Set Up Your Parcl Labs Account

To access property-level data, you'll need to:

  • Create a Parcl Labs account: If you don't already have an account, sign up here.
  • Upgrade your account: Property-level data is a premium feature available only to Starter or Enterprise tier customers. Upgrade your account through your API dashboard to gain access.

Once upgraded, navigate to the dashboard to retrieve your API key. Copy your key and store it securely.


2. Make Your First Property Search Request

The Property Search endpoint is designed to provide you with a comprehensive list of properties based on your specified search parameters. Each property returned in the response is identified by a unique parcl_property_id, which is essential for navigating other property-related endpoints in the Parcl Labs API. As with other endpoints in our API, you will specify parameters to narrow your search and obtain the desired results.

Some of the key parameters to include are:

  • parcl_id (required): This is a unique identifier for a geographic market within the Parcl Labs API. You'll need to provide a parcl_id to specify the market area you are interested in. For example, a parcl_id for Brooklyn, NY will return properties within that specific area. You can find more information about how to search markets here.
  • property_type (required): Specify the type of property you're interested in (e.g., SINGLE_FAMILY, CONDO, TOWNHOUSE,OTHER). This helps to filter the search results based on the property type.
  • Optional Filters: To narrow down your search and optimize credit usage, you can apply additional filters such as:
    • current_entity_owner_name: Filter properties by their current true owner entity, such as large-scale operators like INVITATION_HOMES or TRICON.
    • square_footage_min and square_footage_max: Define the minimum and maximum square footage of the properties you wish to search.
    • bedrooms_min and bedrooms_max: Specify the range for the number of bedrooms.
    • year_built_min and year_built_max: Set the range for the year of construction.
    • Event History Flags: Use flags like event_history_sale_flag, event_history_rental_flag, and event_history_listing_flag to indicate whether a property has observed sales, rentals, or listing events since 2010.

For a complete list of parameters and their descriptions, refer to the API documentation.

You can try a query below using cURL, a widely used command-line tool that developers use to send requests to APIs. Here's an example cURL command you can copy and paste into your terminal. Execute it from your command line to retrieve Single Family Homes in the City of Chicago (5387853) that have been built since 2023, with at least 4 bedrooms and square footage between 5,500 and 6,000. This very tailored request will consume a small amount of credits (8 as of September 2024).

📘

Before running the command:

Replace YOUR_API_KEY with your actual API key.

Example cURL request:

curl --request GET \
     --url 'https://api.parcllabs.com/v1/property/search?parcl_id=5387853&property_type=SINGLE_FAMILY&square_footage_min=5500&square_footage_max=6000&bedrooms_min=5&year_built_min=2023' \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json'

What to expect when you run the command:

  1. The cURL command sends a GET request to the Parcl Labs API, targeting the Property Search endpoint. The request uses the parcl_id to specify the market, such as 5387853 for the City of Chicago.
  2. The API processes the parameters, including property_type and any filters like year_built_min to narrow the search. In this example, the search is narrowed to include only single-family homes built since 2023 that are have a square footage between 5,500 and 6,000.
  3. The API returns a JSON response containing a list of properties that match the criteria you defined. Each property includes detailed information such as address, property type, latitude, longitude, event history flags, and more, all tied to its unique parcl_property_id.

Below is an example of a property returned by the query parameters you submitted in the previous step. This view is just for one property, if your search results return multiple matches every property will have the same information.

Example Response:

{
  "parcl_property_id": 64531491,
  "address": "4323 N BELL AVE",
  "unit": null,
  "city": "CHICAGO",
  "state_abbreviation": "IL",
  "zip5": "60618",
  "zip4": "1609",
  "latitude": 41.960279,
  "longitude": -87.684663,
  "property_type": "SINGLE_FAMILY",
  "bedrooms": 4,
  "bathrooms": 5.0,
  "square_footage": 6000,
  "year_built": 2023,
  "cbsa_parcl_id": 2899845,
  "cbsa_name": "Chicago-Naperville-Elgin, IL-IN-WI",
  "county_parcl_id": 5822729,
  "county_name": "Cook County",
  "city_parcl_id": 5387853,
  "city_name": "Chicago city",
  "zip_parcl_id": 5414139,
  "zip_code": "60618",
  "event_count": 4,
  "event_history_sale_flag": 1,
  "event_history_rental_flag": 0,
  "event_history_listing_flag": 1,
  "current_new_construction_flag": 1,
  "current_owner_occupied_flag": 1,
  "current_investor_owned_flag": 0,
  "current_entity_owner_name": null
}

3. Retrieve Property Event History

Searching for properties and their associated information is just the beginning. Once you have located a property of interest, you can access detailed housing event history using the Property Event History endpoint. This endpoint provides a comprehensive view of a property, allowing you to retrieve information about sales, listings, and rental events. A common use case is to identify units of interest through the property search query and then use the Property Event History endpoint to review their event history (e.g., to understand how many times a house has been sold).

A helpful characteristic of this endpoint is that this is a POST endpoint, allowing you to request many units of history at once.

This endpoint uses the following parameters:

  • parcl_property_id (required): An array of unique property identifiers. These IDs are necessary to specify which properties you want event history for. You can query up to 10,000 properties at once so you save on requests.
  • entity_owner_name: The name of the entity that owns the property at the time of the event, if owned by a named large-scale operator such asTRICON, INVITATION_HOMES, HOME_PARTNERS_OF_AMERICA etc.
  • event_type: Optional. Specify the type of events you want to retrieve, such as SALE, LISTING, or RENTAL. By default, the API returns all event types.
  • start_date and end_date: Define the time range for the events you want to query. Use ISO 8601 format (YYYY-MM-DD). If not provided, the API will return all available events.

📘

Before running the command:

Replace YOUR_API_KEY with your actual API key.

Let's run an example using cURL for the property returned in the previous section.

Example cURL Request:

curl --request POST \
     --url https://api.parcllabs.com/v1/property/event_history \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "parcl_property_id": [
    "64531491"
  ],
  "event_type": "LISTING"
}
'

What to expect when you run the command:

  • When you run the command, the API processes your request and returns a JSON response with detailed event history for each specified property.
  • The API reads the parcl_property_ids to identify the properties and applies any filters you've set, such as:
    • event_type (e.g., LISTING)
    • Date range (start_date and end_date)
  • The API returns only the relevant events based on your filters.
  • Below, you can find the results of the request.

Note: In this example, we will post just one parcl_property_id for simplicity, but the API supports up to 10,000 IDs in a single request.

Example response:

{
  "parcl_property_id": 64531491,
  "event_date": "2024-02-26",
  "event_type": "SALE",
  "event_name": "SOLD",
  "price": 3062000.0,
  "owner_occupied_flag": 1,
  "new_construction_flag": 1,
  "sale_index": 3,
  "investor_flag": 0,
  "entity_owner_name": null
}
{
  "parcl_property_id": 64531491,
  "event_date": "2023-04-10",
  "event_type": "LISTING",
  "event_name": "LISTED_SALE",
  "price": 3200000.0,
  "owner_occupied_flag": 0,
  "new_construction_flag": 1,
  "sale_index": 2,
  "investor_flag": 1,
  "entity_owner_name": null
}
{
  "parcl_property_id": 64531491,
  "event_date": "2022-08-10",
  "event_type": "SALE",
  "event_name": "SOLD",
  "price": 790000.0,
  "owner_occupied_flag": 0,
  "new_construction_flag": 1,
  "sale_index": 2,
  "investor_flag": 1,
  "entity_owner_name": null
}
{
  "parcl_property_id": 64531491,
  "event_date": "2022-06-23",
  "event_type": "LISTING",
  "event_name": "LISTED_SALE",
  "price": 845000.0,
  "owner_occupied_flag": 0,
  "new_construction_flag": 1,
  "sale_index": 1,
  "investor_flag": 1,
  "entity_owner_name": null
}

The result allows our users to track the history of a given property across event types (sales, listings, rentals) alongside other useful information such as if this is an investor property (investor_flag), if its owner_occupied, etc. This enables users to perform sophisticated analyses, such as calculating the gross yield rate for a particular set of units or tracking market movements of large portfolios.


4. Manage Your API Usage and Credits

Understanding how credits are used is important for managing your API usage efficiently:

  • Property Search (GET): Each property returned consumes 1 credit.
  • Property Event History (POST): Each event consumes 1 credit. Total credits used = Number of properties requested × Number of events per property.

Example Credit Usage:

  • Searching for 100 properties: 100 credits
  • Requesting event history for 100 properties, each with 5 events: 500 credits

Keep track of your API usage in real-time by visiting the Parcl Labs dashboard.


5. Start Building

Now that you have tried the property endpoint, you can also explore what else is possible:

  1. Learn by building with our Examples Repository. We've open-sourced our research to help you easily recreate unit-level analyses and data visualizations with just a few clicks.
  2. Install the Parcl Labs Python SDK to efficiently pull property data at scale. The SDK simplifies the process of querying, retrieving, parsing, and formatting the data for you. Here’s an example of how to download property and event data on our repository using the SDK.
  3. We also provide example notebooks for conducting unit-level analysis with step-by-step guides that can be tailored to your use cases. For instance, you can analyze investor ownership concentration or explore what large operators of single-family homes are doing in a given market.
  4. Review the API Reference to explore all available endpoints in the Parcl Labs API.
  5. Get inspired by reviewing our research.
  6. Provide feedback or ask questions in our Developer Forum.

6. Stay Updated

The property-level API is continuously evolving. Keep an eye on the Parcl Labs changelog for updates, including new features and extended data coverage.

For any questions or feedback, please visit our forum or email us at [email protected].