Metadata-Version: 2.3
Name: parcllabs
Version: 0.2.0
Summary: Python SDK for ParclLabs API
Project-URL: Homepage, https://github.com/ParclLabs/parcllabs-python
Author-email: ParclLabs <team@parcllabs.com>
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.
License-File: LICENSE
Keywords: analytics,api,parcllabs,real estate
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: alive-progress
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: requests
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: responses; extra == 'test'
Description-Content-Type: text/markdown

![Logo](img/labs.jpg)
# parcllabs-python

## 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.

## Examples

We maintain a repository of examples that demonstrate how to use the Parcl Labs API for analysis. You can find the examples in the [ParclLabs Examples](https://github.com/parcllabs/parcllabs-examples)

## Installation

You can install the package via pip:

```bash
pip install parcllabs
```


## Getting Started

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('PARCLLABS_API_KEY')
client = ParclLabsClient(api_key)
```

## Search
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
import os

from parcllabs import ParclLabsClient


api_key = os.getenv('PARCLLABS_API_KEY')
client = ParclLabsClient(api_key)

# all cities in EAST_NORTH_CENTRAL census region
results = client.search_markets.retrieve(
    location_type='CITY',
    region='EAST_NORTH_CENTRAL',
    as_dataframe=True
)
print(results.head())
#       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
# 0      5387853     USA  1714000              17                 Chicago City                 IL  EAST_NORTH_CENTRAL          CITY           2721914        71673.0                      1                 1                       0                       0
# 1      5332060     USA  3918000              39                Columbus City                 OH  EAST_NORTH_CENTRAL          CITY            902449        62994.0                      0                 1                       0                       0
# 2      5288667     USA  1836003              18  Indianapolis City (Balance)                 IN  EAST_NORTH_CENTRAL          CITY            882006        59110.0                      0                 0                       0                       0
# 3      5278514     USA  2622000              26                 Detroit City                 MI  EAST_NORTH_CENTRAL          CITY            636787        37761.0                      0                 1                       0                       0
# 4      5333209     USA  5553000              55               Milwaukee City                 WI  EAST_NORTH_CENTRAL          CITY            573299        49733.0                      0                 1                       0                       0
```

## Services

Services are the core of the Parcl Labs API. They provide access to a wide range of data and analytics on the housing market. The services are divided into the following categories: `Price Feeds`, `Rental Market Metrics`, `For Sale Market Metrics`, `Market Metrics`, `Investor Metrics`, and `Portfolio Metrics`.

### Price Feeds
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`.

```python
import os

from parcllabs import ParclLabsClient

api_key = os.getenv('PARCLLABS_API_KEY')
client = ParclLabsClient(api_key)

# Get available Price Feed markets
pricefeed_markets = client.search_markets.retrieve(
        sort_by='PRICEFEED_MARKET',
        sort_order='DESC',
        params={'limit': 10},
        as_dataframe=True
)
pricefeed_ids = pricefeed_markets['parcl_id'].tolist()

price_feeds = client.price_feed.retrieve_many(parcl_ids=pricefeed_ids, as_dataframe=True)
price_feed_volatility = client.price_feed_volatility.retrieve_many(parcl_ids=pricefeed_ids, as_dataframe=True)

# want to save to csv? 
price_feeds.to_csv('price_feeds.csv', index=False)
price_feed_volatility.to_csv('price_feed_volatility.csv', index=False)
```

### Rental Market Metrics

#### 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`.

##### Get all rental market metrics
```python
import os

from parcllabs import ParclLabsClient

api_key = os.getenv('PARCLLABS_API_KEY')
client = ParclLabsClient(api_key)

# get all metros and sort by total population
markets = client.search_markets.retrieve(
        location_type='CBSA',
        sort_by='TOTAL_POPULATION',
        sort_order='DESC',
        as_dataframe=True
    )
# top 10 metros based on population
top_market_parcl_ids = markets['parcl_id'].tolist()[0:10]

start_date = '2020-01-01'
end_date = '2024-04-01'

results_rental_units_concentration = client.rental_market_metrics_rental_units_concentration.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    as_dataframe=True
)

results_gross_yield = client.rental_market_metrics_gross_yield.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    as_dataframe=True
)

rentals_new_listings_rolling_counts = client.rental_market_metrics_new_listings_for_rent_rolling_counts.retrieve_many(
        parcl_ids=[2900187, 5374167],
        as_dataframe=True
    )
```

### For Sale Market Metrics

#### 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`.


##### Get all for sale market metrics
```python
import os

from parcllabs import ParclLabsClient

api_key = os.getenv('PARCLLABS_API_KEY')
client = ParclLabsClient(api_key)

# get all metros and sort by total population
markets = client.search_markets.retrieve(
        location_type='CBSA',
        sort_by='TOTAL_POPULATION',
        sort_order='DESC',
        as_dataframe=True
    )
# top 10 metros based on population
top_market_parcl_ids = markets['parcl_id'].tolist()[0:10]

start_date = '2020-01-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_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    property_type=property_type,
    as_dataframe=True
)
```

### Market Metrics

#### 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`.

#### All Cash
Gets monthly counts of all cash transactions and their percentage share of total sales, based on a specified <parcl_id> .


##### Get all market metrics
```python
import os

from parcllabs import ParclLabsClient


api_key = os.getenv('PARCLLABS_API_KEY')
client = ParclLabsClient(api_key)

# get all metros and sort by total population
markets = client.search_markets.retrieve(
        location_type='CBSA',
        sort_by='TOTAL_POPULATION',
        sort_order='DESC',
        as_dataframe=True
    )
# top 10 metros based on population
top_market_parcl_ids = markets['parcl_id'].tolist()[0:10]

start_date = '2020-01-01'
end_date = '2024-04-01'

results_housing_event_prices = client.market_metrics_housing_event_prices.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    as_dataframe=True
)

results_housing_stock = client.market_metrics_housing_stock.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    as_dataframe=True
)

results_housing_event_counts = client.market_metrics_housing_event_counts.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    as_dataframe=True
)

results_all_cash = client.market_metrics_all_cash.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    as_dataframe=True
)
```

### Investor Metrics

#### 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>.

##### Get all investor metrics
```python
import os

from parcllabs import ParclLabsClient


api_key = os.getenv('PARCLLABS_API_KEY')
client = ParclLabsClient(api_key)

# get all metros and sort by total population
markets = client.search_markets.retrieve(
        location_type='CBSA',
        sort_by='TOTAL_POPULATION',
        sort_order='DESC',
        as_dataframe=True
    )
# top 10 metros based on population
top_market_parcl_ids = markets['parcl_id'].tolist()[0:10]

start_date = '2020-01-01'
end_date = '2024-04-01'

results_housing_stock_ownership = client.investor_metrics_housing_stock_ownership.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    as_dataframe=True
)

results_new_listings_for_sale_rolling_counts = client.investor_metrics_new_listings_for_sale_rolling_counts.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    as_dataframe=True
)

results_purchase_to_sale_ratio = client.investor_metrics_purchase_to_sale_ratio.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    as_dataframe=True
)

results_housing_event_counts = client.investor_metrics_housing_event_counts.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    start_date=start_date,
    end_date=end_date,
    as_dataframe=True
)

results = client.investor_metrics_housing_event_prices.retrieve_many(
        parcl_ids=top_market_parcl_ids,
        start_date=start_date,
        end_date=end_date,
        as_dataframe=True
    )
```

### Portfolio Metrics

#### 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
import os

from parcllabs import ParclLabsClient


api_key = os.getenv('PARCLLABS_API_KEY')
client = ParclLabsClient(api_key)

# get all metros and sort by total population
markets = client.search_markets.retrieve(
        location_type='CBSA',
        sort_by='TOTAL_POPULATION',
        sort_order='DESC',
        as_dataframe=True
    )
# top 10 metros based on population
top_market_parcl_ids = markets['parcl_id'].tolist()[0:10]

results_housing_stock_ownership = client.portfolio_metrics_sf_housing_stock_ownership.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    as_dataframe=True
)

# get new listings for specific portfolio sizes
portfolio_metrics_new_listings = client.portfolio_metrics_new_listings_for_sale_rolling_counts.retrieve_many(
        parcl_ids=top_market_parcl_ids,
        as_dataframe=True,
        portfolio_size='PORTFOLIO_1000_PLUS',
    )

results = client.portfolio_metrics_sf_housing_event_counts.retrieve_many(
    parcl_ids=top_market_parcl_ids,
    as_dataframe=True,
    portfolio_size='PORTFOLIO_1000_PLUS'
)

results = client.portfolio_metrics_sf_new_listings_for_rent_rolling_counts.retrieve_many(
        parcl_ids=top_market_parcl_ids,
        as_dataframe=True,
        portfolio_size='PORTFOLIO_1000_PLUS'
)
```
