May 1, 2023

•

5 min read

Track Your Market Over Time. API Product Release 0.6.0 Blog

0.6.0 API Update: Historical Financial and Inventory Endpoints, New Categories and Two New Markets

At Parcl Labs, we take pride in delivering the most up-to-date, precise, and insightful data on residential real estate, empowering our users to make informed decisions. Our real-time data capabilities set us apart as the only real estate data provider offering daily price points for any US housing market.

This unique feature has paved the way for another groundbreaking addition to Parcl Labs’ API capabilities – the ability to closely monitor market changes over time. Driven by our API beta user community’s feedback, we are thrilled to introduce our most requested API feature: the Historical Financials and Historical Inventory endpoints.

So, what does this mean for you?

With these new endpoints, you can now:

Uncover market trends over time – Identify which markets are more susceptible to fluctuations due to recent macroeconomic shifts, or pinpoint areas where condo construction has outpaced single-family residence development.
Create captivating charts that engage and inform your users – Visually represent historical data, making it easier for your audience to grasp complex trends and insights.
Forecast future trends with greater accuracy – Leverage historical data to make informed predictions, helping you stay ahead of the curve and devise effective strategies for your real estate endeavors.

Ready to get started? Let’s dive in.

Introducing the Historical Inventory Endpoint

With the historical inventory endpoint, you can now access the yearly historical physical inventory for any available market going back to 2010. This data includes the stock of available owner-occupied units broken out by single family residences, townhomes, and condos. The Historical Inventory endpoint can be used to take historical snapshots of markets, track the trend in residential real estate growth over time, or see what property types outpace others.

How can you access historical inventory?

The historical inventory endpoint is accessible at the Parcl Labs documentation site. If you need to register for an API account, start here with our Quickstart guide.

Overview of the metrics returned by historical inventory

The Historical Inventory response object includes the parcl_id and an array of historical inventory data. Each object in the array provides data for a specific date, including the number of available units for each unit type and the total number of units.

Dates for past years are snapped to 12-31, as these objects represent the inventory available at the end of each year. Date for the current year is when this endpoint was last updates, and represents inventory built up until that point. See the full explanation of these metrics.

 
{
    "parcl_id": 2900282,
    "historical_inventory": [
        {
            "date": "2023-04-24",
            "condo": 17039,
            "single_family": 374484,
            "townhouse": 53632,
            "total_units": 445155
        },
        {
            "date": "2022-12-31",
            "condo": 16968,
            "single_family": 372621,
            "townhouse": 53271,
            "total_units": 442860
        },
        {
            "date": "2021-12-31",
            "condo": 16894,
            "single_family": 367050,
            "townhouse": 52807,
            "total_units": 436751
        },
        {
            "date": "2020-12-31",
            "condo": 16732,
            "single_family": 357503,
            "townhouse": 50836,
            "total_units": 425071
        }
    ]
}

Use the Historical Inventory Endpoint to Track Growth Rate over Time

Users can leverage the historical inventory endpoint to track growth trends in residential real estate growth over time, or to see which property types outpace others. See this example recipe to learn how to use this new endpoint with python to track inventory growth rates.

To get started with the Parcl Labs API, please follow the quick start
guide to get your API key:

https://docs.parcllabs.com/docs/quickstart

‍



import os
import requests
import pandas as pd
import matplotlib.pyplot as plt

PARCL_LABS_API_KEY = os.getenv('parcl_labs_api_key') 
PARCL_ID = 5377230 # vegas market

# pass in parcl_id into the url structure, replace with prod URL
url = f'https://api.realestate.parcllabs.com/v1/inventory/{PARCL_ID}/history'

# authorize
header = {
    'Authorization': PARCL_LABS_API_KEY
}

response = requests.get(
    url,
    headers=header
)

# convert the pricefeed key into a pandas dataframe
inventory = pd.DataFrame(response.json()['historical_inventory'])

# Convert the 'date' column to a datetime object
inventory['date'] = pd.to_datetime(inventory['date'])
inventory = inventory.sort_values(by='date', ascending=True)


# Set the 'date' column as the dataframe's index
inventory.set_index('date', inplace=True)

# Calculate percent change for each unit type
inventory['condo_pct_change_from_2010'] = inventory['condo'].pct_change().fillna(0).add(1).cumprod().sub(1).mul(100)
inventory['sfr_pct_change_from_2010'] = inventory['single_family'].pct_change().fillna(0).add(1).cumprod().sub(1).mul(100)
inventory['townhouse_pct_change_from_2010'] = inventory['townhouse'].pct_change().fillna(0).add(1).cumprod().sub(1).mul(100)
inventory['total_pct_change_from_2010'] = inventory['total_units'].pct_change().fillna(0).add(1).cumprod().sub(1).mul(100)

# Create a time series chart using matplotlib
plt.style.use('seaborn-v0_8-darkgrid')
fig, ax = plt.subplots(figsize=(10, 6))

ax.plot(inventory['condo_pct_change_from_2010'], label='Condo')
ax.plot(inventory['sfr_pct_change_from_2010'], label='Single Family')
ax.plot(inventory['townhouse_pct_change_from_2010'], label='Townhouse')
ax.plot(inventory['total_pct_change_from_2010'], label='Total Units')

ax.legend()
ax.set_xlabel('Year')
ax.set_ylabel('Percent Change (%)')
ax.set_title('Las Vegas Inventory Percent Change From 2010')

plt.show()
plt.savefig(f'vegas_inventory.png', dpi=300, bbox_inches='tight', pad_inches=0.25)

This quick recipe outputs a time series graph visualizing inventory growth rates.

Introducing the Financials History Endpoint

With Historical Financials, you can now access historical financial metrics for any given market. These metrics include alpha and beta, correlation coefficient, annual volatility, sharpe_ratio, average return, compound annual growth rate and kurtosis. The historical financial metrics go back to 1/31/2021, with the 1/31/2021 being built from 2020 data.

For example, a metric with a date of 1/31/2010 will include 365 days worth of price feed market data to calculate the average return, compound annual growth rate, annual volatility, etc. Essentially this is a rolling year of data that is indexed at the end of each month. Historical financials provides a monthly checkpoint of the prior year of key financials metrics about any given metric.

How can you access historical financials?

The historical financials endpoint is accessible at the Parcl Labs documentation site. If you need to register for an API account, start here with our Quickstart guide.

Overview of the metrics returned by historical financials

The Historical Financials response object includes monthly financial data for alpha and beta, correlation coefficient, annual volatility, sharpe_ratio, average return, compound annual growth rate and kurtosis. See the full explanation of these metrics.


{
    "parcl_id": 2900187,
    "alpha_beta": {
        "spy": [
            {
                "alpha": 1.7655,
                "beta": -0.0001,
                "date": "2021-01-31"
            },
            {
                "alpha": 1.657,
                "beta": 0.0005,
                "date": "2021-02-28"
            },
            {
                "alpha": 0.0498,
                "beta": 0.0017,
                "date": "2021-03-31"
            }
        ]
    },
    "correlation_coefficient": {
        "mortgage30us": [
            {
                "date": "2021-01-31",
                "pricefeed_corr_coef_lag_2_weeks": -0.7946,
                "pricefeed_corr_coef_lag_4_weeks": -0.7564,
                "pricefeed_corr_coef_lag_6_weeks": -0.8029,
                "pricefeed_corr_coef_lag_8_weeks": -0.7899
            },
            {
                "date": "2021-02-28",
                "pricefeed_corr_coef_lag_2_weeks": -0.77,
                "pricefeed_corr_coef_lag_4_weeks": -0.7774,
                "pricefeed_corr_coef_lag_6_weeks": -0.7293,
                "pricefeed_corr_coef_lag_8_weeks": -0.5186
            },
            {
                "date": "2021-03-31",
                "pricefeed_corr_coef_lag_2_weeks": -0.6318,
                "pricefeed_corr_coef_lag_4_weeks": -0.5135,
                "pricefeed_corr_coef_lag_6_weeks": -0.2148,
                "pricefeed_corr_coef_lag_8_weeks": 0.2187
            }
        ]
    },
    "metrics": [
        {
            "annual_volatility": 0.0142,
            "avg_return": 0.00036,
            "cagr": 0.1383,
            "date": "2021-01-31",
            "excess_kurtosis": -3.75084,
            "kurtosis": -0.75084,
            "sharpe_ratio": 9.13887
        },
        {
            "annual_volatility": 0.0144,
            "avg_return": 0.00029,
            "cagr": 0.113,
            "date": "2021-02-28",
            "excess_kurtosis": -4.30175,
            "kurtosis": -1.30175,
            "sharpe_ratio": 7.44464
        },
        {
            "annual_volatility": 0.0142,
            "avg_return": 0.00034,
            "cagr": 0.1336,
            "date": "2021-03-31",
            "excess_kurtosis": -4.61503,
            "kurtosis": -1.61503,
            "sharpe_ratio": 8.86871
        }
    ]
}

Use the Historical Financials Endpoint to Analyze Market Dynamics over Time

User can now analyze market dynamics over time by leveraging monthly financial data that goes back to 1/31/2021. See this example recipe to learn how to visualize housing market volatility over time:


"""
To get started with the Parcl Labs API, please follow the quick start
guide to get your API key: 

https://docs.parcllabs.com/docs/quickstart
"""

import os
import requests
from datetime import datetime, timedelta

import numpy as np
import pandas as pd
import plotly.express as px


api_key = os.environ['parcl_labs_api_key']

headers = {
    "Authorization": api_key
}


# markets endpoint will provide all parcls available in the API currently along with market metadata like name
markets_endpoint = f"https://api.realestate.parcllabs.com/v1/place/markets"

response = requests.get(markets_endpoint, headers=headers)

markets_json = response.json()


# create data structure for data manipulations and metadata
pids = [
    5332726, # cinci
    5332800, # cleveland
    5328454, # new orleans
    5377717, # pittsburgh
    5307837, # jersey city
    5308252, # Lousiveille
    5353022, # Miami Beach
]
# define data structure for custom collection of data elements
data = {}

for pid in pids:
    for v in markets_json:
        if v['parcl_id'] == pid:
            data[pid] = {'name': v['name'].replace('City', ''), 'state': v['state']}


# financial history endpoint will provide historical financial metrics for
# given parcl_id
vols = []

for pid in data.keys():
    financial_historical_endpoint = f"https://api.realestate.parcllabs.com/v1/financials/{pid}/history"

    response = requests.get(financial_historical_endpoint, headers=headers)

    finanical_json = response.json()
    vol = pd.DataFrame(finanical_json['metrics']).sort_values('date')
    vol['pct_change'] = (1-vol.iloc[0].annual_volatility / vol.annual_volatility)
    vol['Market'] = data[pid]['name']
    data[pid]['vols'] = vol
    vols.append(vol)


# create one data structure
df = pd.concat(vols)


# Create volatility chart
df['date'] = pd.to_datetime(df['date'])

fig1 = px.line(
    df, x='date', 
    y='annual_volatility', 
    color='Market', 
    render_mode='webgl', 
    labels={
    'annual_volatility': "Annual Volatility",
    },
    title='Annual Volatility by Housing Market',
    color_discrete_sequence=px.colors.qualitative.Dark24
)

fig1.update_layout(
    autosize=False,
    width=500,
    height=500,
    title_x=0.5,
    xaxis_title=None
)

fig1.update_xaxes(tickangle=45)
fig1.update_yaxes(tickformat='.0%')

This quick recipe outputs a time series graph visualizing housing volatility for key markets:

Introducing Two New Markets

We are pleased to announce the addition of two new markets: Reno, NV (parcl_id: 5377231) and Broward County, FL (parcl_id: 5821600). With the inclusion of these markets, we are expanding all of our metrics and insights in the API to allow users better understand the trends and dynamics of the real estate industry in these regions.

Introducing New Endpoint Categories and Updated Paths

Introducing three new endpoint categories: financials, inventory, and price_feed, which will make it easier to path the hierarchy of current and historical versions of endpoints. We have refactored existing endpoints to new paths to enable better organization of data. The table below shows the old and new endpoint paths:

Old Endpoint Path → New Endpoint Path

v1/place/<parcl_id>/price_feed → v1/price_feed/<parcl_id>/history

v1/place/<parcl_id>/price_feed_stats → v1/price_feed/<parcl_id>/stats

v1/place/price_feed_last → v1/price_feed/latest

v1/parcls/<parcl_id>/financials → v1/financials/<parcl_id>/current

v1/parcls/<parcl_id>/inventory → v1/inventory/<parcl_id>/current

These updates will allow for more efficient access to relevant data, improving the overall performance of our API. We encourage all users to update their code to reflect these changes to ensure uninterrupted use of our API.

Written by

Zach Shamroukh

Analytics Engineer

Subscribe to our newsletter

Thank you! Your submission has been received!

Oops! Something went wrong while submitting the form.

Share this post





