| Name | parcllabs JSON |
| Version |
1.14.5
JSON |
| download |
| home_page | None |
| Summary | Python SDK for ParclLabs API |
| upload_time | 2025-07-23 14:33:58 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | MIT License
Copyright (c) [2024] [Parcl Labs]
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
analytics
api
parcllabs
real estate
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
pandas
requests
numpy
pydantic
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!-- readme header split -->
<!-- readme header end -->
# Parcl Labs Python SDK
**We're on a mission to create the world's best API developer experience and community for housing data.**
Our SDK is designed to supercharge your API experience and accelerate your time to insight. It enables you to efficiently pull the data you need, analyze it, and visualize your findings.
## Table of Contents
- [Data Overview](#parcl-labs-data-overview)
- [Getting Started](#getting-started)
- [Services](#services)
- [Search](#search)
- [Rental Market Metrics](#rental-market-metrics)
- [For Sale Market Metrics](#for-sale-market-metrics)
- [Market Metrics](#market-metrics)
- [New Construction Metrics](#new-construction-metrics)
- [Investor Metrics](#investor-metrics)
- [Portfolio Metrics](#portfolio-metrics)
- [Price Feeds](#price-feeds)
- [Property](#property)
- [Property Address Search](#property-address-search)
- [Property Search V2](#property-search-v2)
- [Account Info](#account-info)
- [Cookbook](#cookbook)
<!-- readme header split -->
## Parcl Labs Data Overview <a id="parcl-labs-data-overview"></a>
The Parcl Labs API provides **instant insights into the U.S. housing market**, delivering data on housing supply, sales, listings, rentals, investor activities, and market trends.
_The most complete picture of US residential real estate_
| Category | Coverage |
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Property Types** | **🏘️ All Residential Assets:**<br>✅ Single Family<br>✅ Townhouses<br>✅ Condos<br>✅ Other |
| **Markets** | **🇺🇸 Complete National Coverage, 70k+ Unique Markets at Any Level of Granularity:**<br>✅ Regions<br>✅ States<br>✅ Metros<br>✅ Cities<br>✅ Counties<br>✅ Towns<br>✅ Zips<br>✅ Census Places |
| **Housing Events** | **🔄 The Full Property Lifecycle:**<br>✅ Sales<br>✅ For Sale Listings<br>✅ Rentals |
<!-- readme header end -->
## Cookbook <a id="cookbook"></a>
We maintain a repository of examples that demonstrate how to use the Parcl Labs API for analysis. You can find the examples in the [Parcl Labs Cookbook](https://github.com/parcllabs/parcllabs-cookbook)
## Getting Started <a id="getting-started"></a>
### Step 1. Sign Up for an API Key
To use the Parcl Labs API, you need an API key. To get an API key, sign up at [ParclLabs](https://dashboard.parcllabs.com/signup). In the subsequent examples, the API key is stored in the `PARCLLABS_API_KEY` environment variable.
### Step 2. Installation
You can install the package via pip:
```bash
pip install -U parcllabs
```
### Step 3. Usage
The `ParclLabsClient` class is the entry point to the Parcl Labs API. You can use the client to access methods that allow you to retrieve and analyze data from the Parcl Labs API. You'll need to pass in your API key when you create an instance of the `ParclLabsClient` class.
```python
import os
from parcllabs import ParclLabsClient
api_key = os.getenv('PARCL_LABS_API_KEY')
client = ParclLabsClient(api_key)
```
#### Num Workers
The `num_workers` parameter is used to specify the number of workers to use for parallel requests. The default is None, which translates to `min(32, (os.cpu_count() or 1) + 4)`. See [docs](https://github.com/python/cpython/blob/dcc3eaef98cd94d6cb6cb0f44bd1c903d04f33b1/Lib/concurrent/futures/thread.py#L137) for more details.
```python
client = ParclLabsClient(api_key, num_workers=20)
```
## Services <a id="services"></a>
### Search <a id="search"></a>
Search is your entry point into finding one or many of over 70,000 markets in the United States. You can search for markets by `name`, `state`, `region`, `fips`, or `zip code`. You can also search for markets by their unique `parcl_id`.
##### Search Markets
```python
# get top 2 metros by population
markets = client.search.markets.retrieve(
location_type='CBSA',
sort_by='TOTAL_POPULATION',
sort_order='DESC',
limit=2
)
# top 2 metros based on population. We will use these markets to query other services in the remainder of this readme
top_market_parcl_ids = markets['parcl_id'].tolist()
# parcl_id country geoid state_fips_code name state_abbreviation region location_type total_population median_income parcl_exchange_market pricefeed_market case_shiller_10_market case_shiller_20_market
# 2900187 USA 35620 None New York-Newark-Jersey City, Ny-Nj-Pa None None CBSA 19908595 93610 0 1 1 1
# 2900078 USA 31080 None Los Angeles-Long Beach-Anaheim, Ca None None CBSA 13111917 89105 0 1 1 1
```
### Rental Market Metrics <a id="rental-market-metrics"></a>
##### Gross Yield
Gets the percent gross yield for a specified `parcl_id`. At the market level, identified by `parcl_id`, gross yield is calculated by dividing the annual median rental income—derived from multiplying the monthly median new rental listing price by 12—by its median new listings for sale price.
##### Rental Units Concentration
Gets the number of rental units, total units, and percent rental unit concentration for a specified `parcl_id`.
##### New Listings for Rent Rolling Counts
Gets weekly updated rolling counts of newly listed for rent properties, segmented into 7, 30, 60, and 90 day periods ending on a specified date, based on a given `parcl_id`.
```python
start_date = '2024-04-01'
end_date = '2024-04-01'
results_rental_units_concentration = client.rental_market_metrics.rental_units_concentration.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
results_gross_yield = client.rental_market_metrics.gross_yield.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
rentals_new_listings_rolling_counts = client.rental_market_metrics.new_listings_for_rent_rolling_counts.retrieve(
parcl_ids=top_market_parcl_ids
)
```
### For Sale Market Metrics <a id="for-sale-market-metrics"></a>
##### New Listings Rolling Counts
Gets weekly updated rolling counts of newly listed for sale properties, segmented into 7, 30, 60, and 90 day periods ending on a specified date, based on a given `parcl_id`.
##### For Sale Inventory
Gets the weekly updated current count of total inventory listed on market for sale, based on a specified `parcl_id` . The data series for the for sale inventory begins on September 1, 2022 (2022-09-01).
##### For Sale Inventory Price Changes
Gets weekly updated metrics on the price behavior of current for sale inventory, based on a specified `parcl_id`. Available metrics include the count of price changes, count of price drops, median days between price changes, median price change, and the percentage of inventory with price changes. The data series for the for sale inventory metrics begins on September 1, 2022 (2022-09-01).
```python
start_date = '2024-04-01'
end_date = '2024-04-01'
property_type = 'single_family'
results_for_sale_new_listings = client.for_sale_market_metrics.new_listings_rolling_counts.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date,
property_type=property_type
)
for_sale_inventory = client.for_sale_market_metrics.for_sale_inventory.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
for_sale_inventory_price_changes = client.for_sale_market_metrics.for_sale_inventory_price_changes.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date,
)
```
### Market Metrics <a id="market-metrics"></a>
##### Housing Event Counts
Gets monthly counts of housing events, including sales, new sale listings, and new rental listings, based on a specified `parcl_id`.
##### Housing Stock
Gets housing stock for a specified `parcl_id`. Housing stock represents the total number of properties, broken out by single family homes, townhouses, and condos.
##### Housing Event Prices
Gets monthly statistics on prices for housing events, including sales, new for-sale listings, and new rental listings, based on a specified `parcl_id`.
##### Housing Event Property Attributes
Gets monthly statistics on the physical attributes of properties involved in housing events, including sales, new for sale listings, and new rental listings, based on a specified `parcl_id`.
##### All Cash
Gets monthly counts of all cash transactions and their percentage share of total sales, based on a specified `parcl_id`.
```python
start_date = '2024-01-01'
end_date = '2024-04-01'
results_housing_event_prices = client.market_metrics.housing_event_prices.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
results_housing_stock = client.market_metrics.housing_stock.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
results_housing_event_counts = client.market_metrics.housing_event_counts.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
housing_event_property_attributes = client.market_metrics.housing_event_property_attributes.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
results_all_cash = client.market_metrics.all_cash.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
```
### New Construction Metrics <a id="new-construction-metrics"></a>
##### Housing Event Counts
Gets monthly counts of new construction housing events, including sales, new for sale listings, and new rental listings, based on a specified `parcl_id`.
##### Housing Event Prices
Gets monthly median prices for new construction housing events, including sales, new for sale listings, and new rental listings, based on a specified `parcl_id`.
```python
start_date = '2024-01-01'
end_date = '2024-04-01'
results_new_construction_housing_event_prices = client.new_construction_metrics.housing_event_prices.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
results_new_construction_housing_event_counts = client.new_construction_metrics.housing_event_counts.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
```
### Investor Metrics <a id="investor-metrics"></a>
##### Housing Event Counts
Gets monthly counts of investor housing events, including acquisitions, dispositions, new sale listings, and new rental listings, based on a specified `parcl_id`.
##### Purchase to Sale Ratio
Gets the monthly investor purchase to sale ratio for a specified `parcl_id`.
##### New Listings for Sale Rolling Counts
Gets weekly updated rolling counts of investor-owned properties newly listed for sale, and their corresponding percentage share of the total for-sale listings market. These metrics are segmented into 7, 30, 60, and 90-day periods ending on a specified date, based on a given `parcl_id`
##### Housing Stock Ownership
Gets counts of investor-owned properties and their corresponding percentage ownership share of the total housing stock, for a specified `parcl_id`.
##### Housing Event Prices
Gets monthly median prices for investor housing events, including acquisitions, dispositions, new sale listings, and new rental listings, based on a specified `parcl_id`.
```python
start_date = '2024-01-01'
end_date = '2024-04-01'
results_housing_stock_ownership = client.investor_metrics.housing_stock_ownership.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
results_new_listings_for_sale_rolling_counts = client.investor_metrics.new_listings_for_sale_rolling_counts.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
results_purchase_to_sale_ratio = client.investor_metrics.purchase_to_sale_ratio.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
results_housing_event_counts = client.investor_metrics.housing_event_counts.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date
)
results = client.investor_metrics.housing_event_prices.retrieve(
parcl_ids=top_market_parcl_ids,
start_date=start_date,
end_date=end_date,
)
```
### Portfolio Metrics <a id="portfolio-metrics"></a>
##### Single Family Housing Event Counts
Gets monthly counts of investor-owned single family property housing events, segmented by portfolio size, for a specified `parcl_id`. Housing events include acquisitions, dispositions, new for sale listings, and new rental listings.
##### Single Family Housing Stock Ownership
Gets counts of investor-owned single family properties and their corresponding percentage of the total single family housing stock, segmented by portfolio size, for a specified `parcl_id`. The data series for portfolio metrics begins on March 1, 2024 (2024-03-01).
##### New Listings for Sale Rolling Counts
Gets counts of investor-owned single family properties and their corresponding percentage of the total single family housing stock, segmented by portfolio size, for a specified `parcl_id`. The data series for portfolio metrics begins on April 15, 2024 (2024-04-15).
##### New Listings for Rent Rolling Counts
Gets weekly updated rolling counts of investor-owned single family properties newly listed for rent, segmented by portfolio size, and their corresponding percentage share of the total single family for rent listings market. These metrics are divided into 7, 30, 60, and 90 day periods ending on a specified date, based on a given `parcl_id`. The data series for portfolio metrics begins on April 22, 2024 (2024-04-22).
```python
results_housing_stock_ownership = client.portfolio_metrics.sf_housing_stock_ownership.retrieve(
parcl_ids=top_market_parcl_ids,
)
# get new listings for specific portfolio sizes
portfolio_metrics_new_listings = client.portfolio_metrics.sf_new_listings_for_sale_rolling_counts.retrieve(
parcl_ids=top_market_parcl_ids,
portfolio_size='PORTFOLIO_1000_PLUS',
)
results = client.portfolio_metrics.sf_housing_event_counts.retrieve(
parcl_ids=top_market_parcl_ids,
portfolio_size='PORTFOLIO_1000_PLUS'
)
results = client.portfolio_metrics.sf_new_listings_for_rent_rolling_counts.retrieve(
parcl_ids=top_market_parcl_ids,
portfolio_size='PORTFOLIO_1000_PLUS'
)
```
### Price Feeds <a id="price-feeds"></a>
The Parcl Labs Price Feed (PLPF) is a daily-updated, real-time indicator of residential real estate prices, measured by price per square foot, across select US markets.
The Price Feeds category allows you to access our daily-updated PLPF and derivative metrics, such as volatility.
##### Price Feed
Gets the daily price feed for a specified `parcl_id`.
##### Price Feed Volatility
Gets the daily price feed volatility for a specified `parcl_id`.
##### Rental Price Feed
Gets the daily updated Parcl Labs Rental Price Feed for a given `parcl_id`.
```python
# get 2 price feeds trading on the Parcl Exchange
pricefeed_markets = client.search.markets.retrieve(
sort_by='PARCL_EXCHANGE_MARKET', # use PRICEFEED_MARKET for all price feed markets
sort_order='DESC',
limit=2
)
# top 2 metros based on population. We will use these markets to query other services in the remainder of this readme
pricefeed_ids = pricefeed_markets['parcl_id'].tolist()
start_date = '2024-06-01'
end_date = '2024-06-05'
price_feeds = client.price_feed.price_feed.retrieve(
parcl_ids=pricefeed_ids,
start_date=start_date,
end_date=end_date
)
rental_price_feeds = client.price_feed.rental_price_feed.retrieve(
parcl_ids=pricefeed_ids,
start_date=start_date,
end_date=end_date
)
price_feed_volatility = client.price_feed.volatility.retrieve(
parcl_ids=pricefeed_ids,
start_date=start_date,
end_date=end_date
)
```
### Property <a id="property"></a>
##### Property Search Markets
Gets a list of unique identifiers (parcl_property_id) for units that correspond to specific markets or parameters defined by the user. The parcl_property_id is key to navigating the Parcl Labs API, serving as the core mechanism for retrieving unit-level information.
```python
# search by operators
invitation_homes_tampa_units = client.property.search.retrieve(
parcl_ids=[2900417],
property_type='single_family',
# square_footage_min=1000,
# square_footage_max=2500,
# bedrooms_min=2,
# bedrooms_max=5,
# bathrooms_min=2,
# bathrooms_max=3,
# year_built_min=2010,
# year_built_max=2023,
current_entity_owner_name='invitation_homes',
# event_history_sale_flag=True,
# event_history_rental_flag=True,
# event_history_listing_flag=True,
# current_new_oncstruciton_flag=True,
# current_owner_occupied_flag=True,
# current_investor_owned_flag=True,
)
# search by buy box - only look at units that have rented
# and review rental rates
rental_buy_box = client.property.search.retrieve(
parcl_ids=[2900417],
property_type='single_family',
square_footage_min=1000,
square_footage_max=2500,
bedrooms_min=2,
bedrooms_max=5,
# bathrooms_min=2,
# bathrooms_max=3,
year_built_min=2010,
year_built_max=2023,
# current_entity_owner_name='invitation_homes',
# event_history_sale_flag=True,
event_history_rental_flag=True,
# event_history_listing_flag=True,
# current_new_oncstruciton_flag=True,
# current_owner_occupied_flag=True,
# current_investor_owned_flag=True,
)
# to extract parcl_property_id's to retrieve expanded history for
# any of these queries, use:
parcl_property_id_list = rental_buy_box['parcl_property_id'].tolist()
```
##### Property Event History
Gets unit-level properties and their housing event history, including sales, listings, and rentals. The response includes detailed property information and historical event data for each specified property.
```python
sale_events = client.property.events.retrieve(
parcl_property_ids=parcl_property_id_list[0:10],
event_type='SALE',
start_date='2020-01-01',
end_date='2024-06-30'
)
rental_events = client.property.events.retrieve(
parcl_property_ids=parcl_property_id_list[0:10],
event_type='RENTAL',
start_date='2020-01-01',
end_date='2024-06-30'
)
```
### Property Address Search <a id="property-address-search"></a>
Pass in a list of addresses -- `address, unit, city, state_abbreviation, zip_code, source_id` -- and receive the associated `parcl_property_id`, if there is a match. `unit` and `source_id` are optional fields.
```python
addresses = client.property_address.search.retrieve(
addresses=[
{
"address": "123 Main St",
"city": "New York",
"state_abbreviation": "NY",
"zip_code": "10001",
"source_id": "123",
},
{
"address": "6251 coldwater canyon ave",
"unit": "unit 311",
"city": "north hollywood",
"state_abbreviation": "CA",
"zip_code": "91606",
"source_id": "456",
},
]
)
```
### Property Search V2 <a id="property-search-v2"></a>
Gets a list of unique properties and their associated metadata and events based on a set of property, event, and owner filters. Use one of three search methods:
1. `parcl_ids`
2. `parcl_property_ids`
3. `geo_coordinates` (must provide latitude, longitude, and radius)
**NOTE:** Use the `limit` parameter to specify the number of matched properties to return. If `limit` is not provided, all matched properties will be returned. Conceptually, you should set the `limit` to retrieve a sample of properties, and then if you want to retrieve all properties, make the same request again without the `limit` parameter.
Example request, note that only one of `parcl_ids`, `parcl_property_ids`, or `geo_coordinates` can be provided per request:
```python
results, filter_data = client.property_v2.search.retrieve(
# parcl_ids=[5495449],
parcl_property_ids=[78353317, 135921544],
# geo_coordinates= {"latitude": 36.159445, "longitude": -86.483244, radius: 1},
event_names=["LISTED_RENT"],
is_new_construction=False,
max_event_date="2024-12-31",
min_event_date="2023-01-01",
max_price=3000,
min_price=100,
is_investor_owned=True,
is_owner_occupied=False,
owner_name=["BLACKSTONE"],
include_property_details=True,
max_beds=5,
min_beds=1,
max_year_built=2020,
min_year_built=1998,
min_baths=1,
min_sqft=500,
max_record_added_date="2024-12-31",
min_record_added_date="2024-12-13",
property_types=["SINGLE_FAMILY", "CONDO", "TOWNHOUSE"],
limit=100,
)
```
### Account Info <a id="account-info"></a>
Monitor your API usage and quota limits by calling the `account()` method in the `ParclLabsClient` class.
```python
client = ParclLabsClient(api_key)
account_info = client.account()
```
Raw data
{
"_id": null,
"home_page": null,
"name": "parcllabs",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "analytics, api, parcllabs, real estate",
"author": null,
"author_email": "ParclLabs <team@parcllabs.com>",
"download_url": "https://files.pythonhosted.org/packages/d1/99/cb854356a97ff54a407a0a8025f6562772238357e1ce9e7b46b7d856e5f7/parcllabs-1.14.5.tar.gz",
"platform": null,
"description": "<!-- readme header split -->\n\n\n\n<!-- readme header end -->\n\n# Parcl Labs Python SDK\n\n**We're on a mission to create the world's best API developer experience and community for housing data.**\n\nOur SDK is designed to supercharge your API experience and accelerate your time to insight. It enables you to efficiently pull the data you need, analyze it, and visualize your findings.\n\n## Table of Contents\n- [Data Overview](#parcl-labs-data-overview)\n- [Getting Started](#getting-started)\n- [Services](#services)\n - [Search](#search)\n - [Rental Market Metrics](#rental-market-metrics)\n - [For Sale Market Metrics](#for-sale-market-metrics)\n - [Market Metrics](#market-metrics)\n - [New Construction Metrics](#new-construction-metrics)\n - [Investor Metrics](#investor-metrics)\n - [Portfolio Metrics](#portfolio-metrics)\n - [Price Feeds](#price-feeds)\n - [Property](#property)\n - [Property Address Search](#property-address-search)\n - [Property Search V2](#property-search-v2)\n - [Account Info](#account-info)\n- [Cookbook](#cookbook)\n\n<!-- readme header split -->\n## Parcl Labs Data Overview <a id=\"parcl-labs-data-overview\"></a>\n\nThe Parcl Labs API provides **instant insights into the U.S. housing market**, delivering data on housing supply, sales, listings, rentals, investor activities, and market trends.\n\n_The most complete picture of US residential real estate_\n\n| Category | Coverage |\n|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **Property Types** | **\ud83c\udfd8\ufe0f All Residential Assets:**<br>\u2705 Single Family<br>\u2705 Townhouses<br>\u2705 Condos<br>\u2705 Other |\n| **Markets** | **\ud83c\uddfa\ud83c\uddf8 Complete National Coverage, 70k+ Unique Markets at Any Level of Granularity:**<br>\u2705 Regions<br>\u2705 States<br>\u2705 Metros<br>\u2705 Cities<br>\u2705 Counties<br>\u2705 Towns<br>\u2705 Zips<br>\u2705 Census Places |\n| **Housing Events** | **\ud83d\udd04 The Full Property Lifecycle:**<br>\u2705 Sales<br>\u2705 For Sale Listings<br>\u2705 Rentals |\n<!-- readme header end -->\n\n## Cookbook <a id=\"cookbook\"></a>\n\nWe maintain a repository of examples that demonstrate how to use the Parcl Labs API for analysis. You can find the examples in the [Parcl Labs Cookbook](https://github.com/parcllabs/parcllabs-cookbook)\n\n## Getting Started <a id=\"getting-started\"></a>\n\n### Step 1. Sign Up for an API Key\n\nTo use the Parcl Labs API, you need an API key. To get an API key, sign up at [ParclLabs](https://dashboard.parcllabs.com/signup). In the subsequent examples, the API key is stored in the `PARCLLABS_API_KEY` environment variable.\n\n### Step 2. Installation\n\nYou can install the package via pip:\n\n```bash\npip install -U parcllabs\n```\n\n### Step 3. Usage\n\nThe `ParclLabsClient` class is the entry point to the Parcl Labs API. You can use the client to access methods that allow you to retrieve and analyze data from the Parcl Labs API. You'll need to pass in your API key when you create an instance of the `ParclLabsClient` class.\n\n```python\nimport os\n\nfrom parcllabs import ParclLabsClient\n\n\napi_key = os.getenv('PARCL_LABS_API_KEY')\nclient = ParclLabsClient(api_key)\n```\n\n#### Num Workers\n\nThe `num_workers` parameter is used to specify the number of workers to use for parallel requests. The default is None, which translates to `min(32, (os.cpu_count() or 1) + 4)`. See [docs](https://github.com/python/cpython/blob/dcc3eaef98cd94d6cb6cb0f44bd1c903d04f33b1/Lib/concurrent/futures/thread.py#L137) for more details. \n\n```python\nclient = ParclLabsClient(api_key, num_workers=20)\n```\n\n## Services <a id=\"services\"></a>\n\n### Search <a id=\"search\"></a>\n\nSearch is your entry point into finding one or many of over 70,000 markets in the United States. You can search for markets by `name`, `state`, `region`, `fips`, or `zip code`. You can also search for markets by their unique `parcl_id`.\n\n##### Search Markets\n```python\n# get top 2 metros by population\nmarkets = client.search.markets.retrieve(\n location_type='CBSA',\n sort_by='TOTAL_POPULATION',\n sort_order='DESC',\n limit=2\n)\n# top 2 metros based on population. We will use these markets to query other services in the remainder of this readme\ntop_market_parcl_ids = markets['parcl_id'].tolist()\n# parcl_id country geoid state_fips_code name state_abbreviation region location_type total_population median_income parcl_exchange_market pricefeed_market case_shiller_10_market case_shiller_20_market\n# 2900187 USA 35620 None New York-Newark-Jersey City, Ny-Nj-Pa None None CBSA 19908595 93610 0 1 1 1\n# 2900078 USA 31080 None Los Angeles-Long Beach-Anaheim, Ca None None CBSA 13111917 89105 0 1 1 1\n```\n\n### Rental Market Metrics <a id=\"rental-market-metrics\"></a>\n\n##### Gross Yield\nGets the percent gross yield for a specified `parcl_id`. At the market level, identified by `parcl_id`, gross yield is calculated by dividing the annual median rental income\u2014derived from multiplying the monthly median new rental listing price by 12\u2014by its median new listings for sale price.\n\n##### Rental Units Concentration\nGets the number of rental units, total units, and percent rental unit concentration for a specified `parcl_id`.\n\n##### New Listings for Rent Rolling Counts\nGets weekly updated rolling counts of newly listed for rent properties, segmented into 7, 30, 60, and 90 day periods ending on a specified date, based on a given `parcl_id`.\n\n```python\nstart_date = '2024-04-01'\nend_date = '2024-04-01'\n\nresults_rental_units_concentration = client.rental_market_metrics.rental_units_concentration.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nresults_gross_yield = client.rental_market_metrics.gross_yield.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nrentals_new_listings_rolling_counts = client.rental_market_metrics.new_listings_for_rent_rolling_counts.retrieve(\n parcl_ids=top_market_parcl_ids\n)\n```\n\n### For Sale Market Metrics <a id=\"for-sale-market-metrics\"></a>\n\n##### New Listings Rolling Counts\nGets weekly updated rolling counts of newly listed for sale properties, segmented into 7, 30, 60, and 90 day periods ending on a specified date, based on a given `parcl_id`.\n\n##### For Sale Inventory\nGets the weekly updated current count of total inventory listed on market for sale, based on a specified `parcl_id` . The data series for the for sale inventory begins on September 1, 2022 (2022-09-01).\n\n##### For Sale Inventory Price Changes\nGets weekly updated metrics on the price behavior of current for sale inventory, based on a specified `parcl_id`. Available metrics include the count of price changes, count of price drops, median days between price changes, median price change, and the percentage of inventory with price changes. The data series for the for sale inventory metrics begins on September 1, 2022 (2022-09-01).\n\n```python\nstart_date = '2024-04-01'\nend_date = '2024-04-01'\nproperty_type = 'single_family'\n\nresults_for_sale_new_listings = client.for_sale_market_metrics.new_listings_rolling_counts.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date,\n property_type=property_type\n)\n\nfor_sale_inventory = client.for_sale_market_metrics.for_sale_inventory.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nfor_sale_inventory_price_changes = client.for_sale_market_metrics.for_sale_inventory_price_changes.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date,\n)\n```\n\n### Market Metrics <a id=\"market-metrics\"></a>\n\n##### Housing Event Counts\nGets monthly counts of housing events, including sales, new sale listings, and new rental listings, based on a specified `parcl_id`.\n\n##### Housing Stock\nGets housing stock for a specified `parcl_id`. Housing stock represents the total number of properties, broken out by single family homes, townhouses, and condos.\n\n##### Housing Event Prices\nGets monthly statistics on prices for housing events, including sales, new for-sale listings, and new rental listings, based on a specified `parcl_id`.\n\n##### Housing Event Property Attributes\nGets monthly statistics on the physical attributes of properties involved in housing events, including sales, new for sale listings, and new rental listings, based on a specified `parcl_id`.\n\n##### All Cash\nGets monthly counts of all cash transactions and their percentage share of total sales, based on a specified `parcl_id`.\n\n```python\nstart_date = '2024-01-01'\nend_date = '2024-04-01'\n\nresults_housing_event_prices = client.market_metrics.housing_event_prices.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nresults_housing_stock = client.market_metrics.housing_stock.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nresults_housing_event_counts = client.market_metrics.housing_event_counts.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nhousing_event_property_attributes = client.market_metrics.housing_event_property_attributes.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nresults_all_cash = client.market_metrics.all_cash.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n```\n\n### New Construction Metrics <a id=\"new-construction-metrics\"></a>\n\n##### Housing Event Counts\nGets monthly counts of new construction housing events, including sales, new for sale listings, and new rental listings, based on a specified `parcl_id`.\n\n##### Housing Event Prices\nGets monthly median prices for new construction housing events, including sales, new for sale listings, and new rental listings, based on a specified `parcl_id`.\n\n```python\nstart_date = '2024-01-01'\nend_date = '2024-04-01'\n\nresults_new_construction_housing_event_prices = client.new_construction_metrics.housing_event_prices.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nresults_new_construction_housing_event_counts = client.new_construction_metrics.housing_event_counts.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n```\n\n### Investor Metrics <a id=\"investor-metrics\"></a>\n\n##### Housing Event Counts\nGets monthly counts of investor housing events, including acquisitions, dispositions, new sale listings, and new rental listings, based on a specified `parcl_id`.\n\n##### Purchase to Sale Ratio\nGets the monthly investor purchase to sale ratio for a specified `parcl_id`.\n\n##### New Listings for Sale Rolling Counts\nGets weekly updated rolling counts of investor-owned properties newly listed for sale, and their corresponding percentage share of the total for-sale listings market. These metrics are segmented into 7, 30, 60, and 90-day periods ending on a specified date, based on a given `parcl_id`\n\n##### Housing Stock Ownership\nGets counts of investor-owned properties and their corresponding percentage ownership share of the total housing stock, for a specified `parcl_id`.\n\n##### Housing Event Prices\nGets monthly median prices for investor housing events, including acquisitions, dispositions, new sale listings, and new rental listings, based on a specified `parcl_id`.\n\n```python\nstart_date = '2024-01-01'\nend_date = '2024-04-01'\n\nresults_housing_stock_ownership = client.investor_metrics.housing_stock_ownership.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nresults_new_listings_for_sale_rolling_counts = client.investor_metrics.new_listings_for_sale_rolling_counts.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nresults_purchase_to_sale_ratio = client.investor_metrics.purchase_to_sale_ratio.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nresults_housing_event_counts = client.investor_metrics.housing_event_counts.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date\n)\n\nresults = client.investor_metrics.housing_event_prices.retrieve(\n parcl_ids=top_market_parcl_ids,\n start_date=start_date,\n end_date=end_date,\n)\n```\n\n### Portfolio Metrics <a id=\"portfolio-metrics\"></a>\n\n##### Single Family Housing Event Counts\nGets monthly counts of investor-owned single family property housing events, segmented by portfolio size, for a specified `parcl_id`. Housing events include acquisitions, dispositions, new for sale listings, and new rental listings.\n\n##### Single Family Housing Stock Ownership\nGets counts of investor-owned single family properties and their corresponding percentage of the total single family housing stock, segmented by portfolio size, for a specified `parcl_id`. The data series for portfolio metrics begins on March 1, 2024 (2024-03-01).\n\n##### New Listings for Sale Rolling Counts\nGets counts of investor-owned single family properties and their corresponding percentage of the total single family housing stock, segmented by portfolio size, for a specified `parcl_id`. The data series for portfolio metrics begins on April 15, 2024 (2024-04-15).\n\n##### New Listings for Rent Rolling Counts\nGets weekly updated rolling counts of investor-owned single family properties newly listed for rent, segmented by portfolio size, and their corresponding percentage share of the total single family for rent listings market. These metrics are divided into 7, 30, 60, and 90 day periods ending on a specified date, based on a given `parcl_id`. The data series for portfolio metrics begins on April 22, 2024 (2024-04-22).\n\n```python\nresults_housing_stock_ownership = client.portfolio_metrics.sf_housing_stock_ownership.retrieve(\n parcl_ids=top_market_parcl_ids,\n)\n\n# get new listings for specific portfolio sizes\nportfolio_metrics_new_listings = client.portfolio_metrics.sf_new_listings_for_sale_rolling_counts.retrieve(\n parcl_ids=top_market_parcl_ids,\n portfolio_size='PORTFOLIO_1000_PLUS',\n)\n\nresults = client.portfolio_metrics.sf_housing_event_counts.retrieve(\n parcl_ids=top_market_parcl_ids,\n portfolio_size='PORTFOLIO_1000_PLUS'\n)\n\nresults = client.portfolio_metrics.sf_new_listings_for_rent_rolling_counts.retrieve(\n parcl_ids=top_market_parcl_ids,\n portfolio_size='PORTFOLIO_1000_PLUS'\n)\n```\n\n### Price Feeds <a id=\"price-feeds\"></a>\n\nThe Parcl Labs Price Feed (PLPF) is a daily-updated, real-time indicator of residential real estate prices, measured by price per square foot, across select US markets.\n\nThe Price Feeds category allows you to access our daily-updated PLPF and derivative metrics, such as volatility.\n\n##### Price Feed\nGets the daily price feed for a specified `parcl_id`.\n\n##### Price Feed Volatility\nGets the daily price feed volatility for a specified `parcl_id`.\n\n##### Rental Price Feed\nGets the daily updated Parcl Labs Rental Price Feed for a given `parcl_id`.\n\n```python\n# get 2 price feeds trading on the Parcl Exchange\npricefeed_markets = client.search.markets.retrieve(\n sort_by='PARCL_EXCHANGE_MARKET', # use PRICEFEED_MARKET for all price feed markets\n sort_order='DESC',\n limit=2\n)\n# top 2 metros based on population. We will use these markets to query other services in the remainder of this readme\npricefeed_ids = pricefeed_markets['parcl_id'].tolist()\nstart_date = '2024-06-01'\nend_date = '2024-06-05'\n\nprice_feeds = client.price_feed.price_feed.retrieve(\n parcl_ids=pricefeed_ids,\n start_date=start_date,\n end_date=end_date\n)\nrental_price_feeds = client.price_feed.rental_price_feed.retrieve(\n parcl_ids=pricefeed_ids,\n start_date=start_date,\n end_date=end_date\n)\nprice_feed_volatility = client.price_feed.volatility.retrieve(\n parcl_ids=pricefeed_ids,\n start_date=start_date,\n end_date=end_date\n)\n```\n\n### Property <a id=\"property\"></a>\n\n##### Property Search Markets\nGets a list of unique identifiers (parcl_property_id) for units that correspond to specific markets or parameters defined by the user. The parcl_property_id is key to navigating the Parcl Labs API, serving as the core mechanism for retrieving unit-level information.\n\n```python\n# search by operators\ninvitation_homes_tampa_units = client.property.search.retrieve(\n parcl_ids=[2900417],\n property_type='single_family',\n # square_footage_min=1000,\n # square_footage_max=2500,\n # bedrooms_min=2,\n # bedrooms_max=5,\n # bathrooms_min=2,\n # bathrooms_max=3,\n # year_built_min=2010,\n # year_built_max=2023,\n current_entity_owner_name='invitation_homes',\n # event_history_sale_flag=True,\n # event_history_rental_flag=True,\n # event_history_listing_flag=True,\n # current_new_oncstruciton_flag=True,\n # current_owner_occupied_flag=True,\n # current_investor_owned_flag=True,\n)\n\n# search by buy box - only look at units that have rented\n# and review rental rates\nrental_buy_box = client.property.search.retrieve(\n parcl_ids=[2900417],\n property_type='single_family',\n square_footage_min=1000,\n square_footage_max=2500,\n bedrooms_min=2,\n bedrooms_max=5,\n # bathrooms_min=2,\n # bathrooms_max=3,\n year_built_min=2010,\n year_built_max=2023,\n # current_entity_owner_name='invitation_homes',\n # event_history_sale_flag=True,\n event_history_rental_flag=True,\n # event_history_listing_flag=True,\n # current_new_oncstruciton_flag=True,\n # current_owner_occupied_flag=True,\n # current_investor_owned_flag=True,\n)\n\n# to extract parcl_property_id's to retrieve expanded history for \n# any of these queries, use: \nparcl_property_id_list = rental_buy_box['parcl_property_id'].tolist()\n```\n\n##### Property Event History\nGets unit-level properties and their housing event history, including sales, listings, and rentals. The response includes detailed property information and historical event data for each specified property.\n\n```python\nsale_events = client.property.events.retrieve(\n parcl_property_ids=parcl_property_id_list[0:10],\n event_type='SALE',\n start_date='2020-01-01',\n end_date='2024-06-30'\n)\n\nrental_events = client.property.events.retrieve(\n parcl_property_ids=parcl_property_id_list[0:10],\n event_type='RENTAL',\n start_date='2020-01-01',\n end_date='2024-06-30'\n)\n```\n\n### Property Address Search <a id=\"property-address-search\"></a>\n\nPass in a list of addresses -- `address, unit, city, state_abbreviation, zip_code, source_id` -- and receive the associated `parcl_property_id`, if there is a match. `unit` and `source_id` are optional fields.\n\n```python\naddresses = client.property_address.search.retrieve(\n addresses=[\n {\n \"address\": \"123 Main St\",\n \"city\": \"New York\",\n \"state_abbreviation\": \"NY\",\n \"zip_code\": \"10001\",\n \"source_id\": \"123\",\n },\n {\n \"address\": \"6251 coldwater canyon ave\",\n \"unit\": \"unit 311\",\n \"city\": \"north hollywood\",\n \"state_abbreviation\": \"CA\",\n \"zip_code\": \"91606\",\n \"source_id\": \"456\",\n },\n ]\n)\n```\n\n### Property Search V2 <a id=\"property-search-v2\"></a>\n\nGets a list of unique properties and their associated metadata and events based on a set of property, event, and owner filters. Use one of three search methods:\n1. `parcl_ids`\n2. `parcl_property_ids`\n3. `geo_coordinates` (must provide latitude, longitude, and radius)\n\n**NOTE:** Use the `limit` parameter to specify the number of matched properties to return. If `limit` is not provided, all matched properties will be returned. Conceptually, you should set the `limit` to retrieve a sample of properties, and then if you want to retrieve all properties, make the same request again without the `limit` parameter.\n\n\nExample request, note that only one of `parcl_ids`, `parcl_property_ids`, or `geo_coordinates` can be provided per request:\n\n```python\nresults, filter_data = client.property_v2.search.retrieve(\n # parcl_ids=[5495449],\n parcl_property_ids=[78353317, 135921544],\n # geo_coordinates= {\"latitude\": 36.159445, \"longitude\": -86.483244, radius: 1},\n event_names=[\"LISTED_RENT\"],\n is_new_construction=False,\n max_event_date=\"2024-12-31\",\n min_event_date=\"2023-01-01\",\n max_price=3000,\n min_price=100,\n is_investor_owned=True,\n is_owner_occupied=False,\n owner_name=[\"BLACKSTONE\"],\n include_property_details=True,\n max_beds=5,\n min_beds=1,\n max_year_built=2020,\n min_year_built=1998,\n min_baths=1,\n min_sqft=500,\n max_record_added_date=\"2024-12-31\",\n min_record_added_date=\"2024-12-13\",\n property_types=[\"SINGLE_FAMILY\", \"CONDO\", \"TOWNHOUSE\"],\n limit=100,\n)\n```\n\n### Account Info <a id=\"account-info\"></a>\n\nMonitor your API usage and quota limits by calling the `account()` method in the `ParclLabsClient` class.\n```python\nclient = ParclLabsClient(api_key)\naccount_info = client.account()\n```\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) [2024] [Parcl Labs]\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Python SDK for ParclLabs API",
"version": "1.14.5",
"project_urls": {
"Homepage": "https://github.com/ParclLabs/parcllabs-python"
},
"split_keywords": [
"analytics",
" api",
" parcllabs",
" real estate"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "958c1e79f75c5e60c3270c994aa60c92ae68e5bfa5f0a2a1187b86d509d69e3f",
"md5": "71c9c03aedb7c476273fa271bf5d5370",
"sha256": "103627483647152716b2514783f72747764d1062d22cc95088802c6dc425e0f0"
},
"downloads": -1,
"filename": "parcllabs-1.14.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "71c9c03aedb7c476273fa271bf5d5370",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 34418,
"upload_time": "2025-07-23T14:33:57",
"upload_time_iso_8601": "2025-07-23T14:33:57.094567Z",
"url": "https://files.pythonhosted.org/packages/95/8c/1e79f75c5e60c3270c994aa60c92ae68e5bfa5f0a2a1187b86d509d69e3f/parcllabs-1.14.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d199cb854356a97ff54a407a0a8025f6562772238357e1ce9e7b46b7d856e5f7",
"md5": "19034e25c8e3ac0d3873fbfa050a16b5",
"sha256": "b10329b1cca171341786e79de2e19abe017f742d4f0aaeb0eb5435ad44df43f3"
},
"downloads": -1,
"filename": "parcllabs-1.14.5.tar.gz",
"has_sig": false,
"md5_digest": "19034e25c8e3ac0d3873fbfa050a16b5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27798,
"upload_time": "2025-07-23T14:33:58",
"upload_time_iso_8601": "2025-07-23T14:33:58.227612Z",
"url": "https://files.pythonhosted.org/packages/d1/99/cb854356a97ff54a407a0a8025f6562772238357e1ce9e7b46b7d856e5f7/parcllabs-1.14.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 14:33:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ParclLabs",
"github_project": "parcllabs-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pandas",
"specs": [
[
">=",
"1.2"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"2.1.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
}
],
"lcname": "parcllabs"
}
