Python Library

pip install -U parcllabs

import os

from parcllabs import ParclLabsClient


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

# 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

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
)

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,
)

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
)

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
)

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,
)

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'
)

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

# want to save to csv? Use .to_csv method as follow:
# price_feeds.to_csv('price_feeds.csv', index=False)
# rental_price_feeds.to_csv('rental_price_feeds.csv', index=False)
# price_feed_volatility.to_csv('price_feed_volatility.csv', index=False)

# search by operators
invitation_homes_tampa_units = client.property.search.retrieve(
    parcl_ids=[2900417],
    property_type='single_family',
    # square_footage_min=1000,
    # quare_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()

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'
)

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",
        },
    ]
)

client = ParclLabsClient(api_key, turbo_mode=True)