Quickstart

Overview

Most applications will use an existing wrapper library in the language of your choice, but it's important to familiarize yourself with the underlying API HTTP methods first.

No better way than to kick the tires than through cURL.

Register for API Key

🚧
Before you do anything....
Make sure you register for an API key. All examples will require having an API key. It's free to register and way more fun.

Registering for the API is easy. We created a short video below that steps through it:

Hello World

Let's start by testing our setup. Open up a command prompt and enter the following command, replacing api_key with your api key after logging into docs.parcllabs.com

Lets GET all available markets in NY state currently provided with daily pricing

# Get markets available in API
curl --request GET \
     --url 'https://api.realestate.parcllabs.com/v1/place/markets?state_abbreviation=NY' \
     --header 'Authorization: api_key' \
     --header 'accept: application/json'

Which gives us the following response:

[
  {
    "parcl_id": 5822447,
    "location_type": "COUNTY",
    "name": "Brooklyn County",
    "state": "NY",
    "state_name": "New York",
    "state_fips_code": "36",
    "census_region": "Middle Atlantic"
  },
  {
    "parcl_id": 5822484,
    "location_type": "COUNTY",
    "name": "Manhattan",
    "state": "NY",
    "state_name": "New York",
    "state_fips_code": "36",
    "census_region": "Middle Atlantic"
  },
  {
    "parcl_id": 2900187,
    "location_type": "MSA",
    "name": "New York",
    "state": "NY",
    "state_name": "New York",
    "state_fips_code": "36",
    "census_region": "Middle Atlantic"
  },
  {
    "parcl_id": 5372594,
    "location_type": "CITY",
    "name": "New York",
    "state": "NY",
    "state_name": "New York",
    "state_fips_code": "36",
    "census_region": "Middle Atlantic"
  }
]

This is the simplest way to view every parcl_id available, which is the starting point to being able to access real time price feeds, market summaries, weather and demographics.

To test our different real estate markets, modify the url and insert a parcl_id into {parcl_id}:

https://api.realestate.parcllabs.com/v1/price_feed/{parcl_id}/history

Let's pull the last year of residential real estate pricing information for the Las Vegas housing market knowing that the Las Vegas parcl_id is 2900049

curl --request GET \
     --url 'https://api.realestate.parcllabs.com/v1/price_feed/2900049/history?start=2023-08-22&end=2023-08-31&order=desc' \
     --header 'Authorization: api_key' \
     --header 'accept: application/json'

This gives us the following response:

{
  "parcl_id": 2900049,
  "name": "Las Vegas",
  "location_type": "MSA",
  "currency": "USD",
  "metric": "SQUARE_FOOT",
  "price_feed": [
    {
      "date": "2023-08-31",
      "price": 254.44
    },
    {
      "date": "2023-08-30",
      "price": 254.43
    },
    {
      "date": "2023-08-29",
      "price": 254.43
    },
    {
      "date": "2023-08-28",
      "price": 254.18
    },
    {
      "date": "2023-08-27",
      "price": 254.04
    },
    {
      "date": "2023-08-26",
      "price": 253.91
    },
    {
      "date": "2023-08-25",
      "price": 253.77
    },
    {
      "date": "2023-08-24",
      "price": 253.51
    },
    {
      "date": "2023-08-23",
      "price": 253.25
    },
    {
      "date": "2023-08-22",
      "price": 252.99
    }
  ]
}

📘
The Power of the Markets Endpoint
Did you know that by using the markets endpoint, you can programmatically traverse all markets of interest and secure each markets price feed in just a couple lines of code?

The power of the markets endpoint is using it as a central hub for programmatically traversing markets across the country. Lets get all housing price feeds for every market in New York.

import os
import requests

api_key = os.environ['parcl_labs_api_key']

headers = {
    "Authorization": api_key
}

params = {
    'state_abbreviation': 'NY'
}


# markets endpoint will provide all <parcls> available in the API currently
markets_endpoint = "https://api.realestate.parcllabs.com/v1/place/markets"

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

markets_json = response.json()

for market in markets_json:
  price_feed_endpoint = f"https://api.realestate.parcllabs.com/v1/price_feed/{parcl_id}/history" 
    
  response = requests.get(
        price_feed_endpoint, 
        params=params, 
        headers=headers
    ).json()
  
  market['price_feed'] = response['price_feed']

Below is a cheat sheet for major metro areas, however we strongly advise using the https://api.realestate.parcllabs.com/v1/place/markets endpoint

Metro Area	Parcl Labs Market ID
San Francisco	2900336
Los Angeles	2900078
New York	2900187
Phoenix	2900245
San Diego	2900332
Seattle	2900353
Chicago	2899845
Miami	2900128
Boston	2899625
Denver	2899750
Atlanta	2887280
Las Vegas	2900049
Washington, DC	2900475
Tampa	2900417
Portland	2900266
Minneapolis	2900137
Charlotte	2899841
Detroit	2899753
Cleveland	2899654

And there you have it, now you can start building real estate applications using daily residential real estate for major markets across the country.

Using headers

To use the Parcl Labs REST API, you will need to pass in a header for the Authorization.

To send a header in a curl command, use the --header or -H flag followed by the header in the key: value format.

# GET /v1/place/2900187/demographics
curl --request GET \
     --url 'https://api.realestate.parcllabs.com/v1/place/2900187/demographics' \
     --header 'Authorization: api_key' \
     --header 'accept: application/json'

Which gives us:

{
  "parcl_id": "2900187",
  "employment": [
    {
      "value": 8950832,
      "variable": "emp_pop_employed",
      "year": 2013
    },
    {
      "value": 9056397,
      "variable": "emp_pop_employed",
      "year": 2014
    },
    {
      "value": 9200185,
      "variable": "emp_pop_employed",
      "year": 2015
    },
    {
      "value": 9311834,
      "variable": "emp_pop_employed",
      "year": 2016
    },
    {
      "value": 9477470,
      "variable": "emp_pop_employed",
      "year": 2017
    },
    {
      "value": 9461407,
      "variable": "emp_pop_employed",
      "year": 2018
    },
    {
      "value": 9533728,
      "variable": "emp_pop_employed",
      "year": 2019
    },
    {
      "value": 9492974,
      "variable": "emp_pop_employed",
      "year": 2020
    },
    {
      "value": 9810131,
      "variable": "emp_pop_employed",
      "year": 2021
    },
    ...
    ]

Using path parameters

Path parameters modify the operation path. For example, the "Get Demographics" path is /v1/place/{parcl_id}/demographics. The curly brackets {} denote path parameters that you need to specify. In this case, you must specify the specific real estate market. Top parcl_id's are provided in the table What MSAs are included in the API?

To get demographics from the Cleveland market with a parcl_id of 2899654, replace {parcl_id} with 2899654. To build the full path, prepend the base URL for the Parcl Labs REST API https://api.realesetate.parcllabs.com/api: https://api.realestate.parcllabs.com/api/place/2900187/demographics

# GET /v1/place/2900187/demographics
curl --request GET \
     --url 'https://api.realestate.parcllabs.com/v1/place/2900187/demographics' \
     --header 'Authorization: api_key' \
     --header 'accept: application/json'

The operation returns a categorized list of demographics variables organized by income, age, employment and our own friendly categories.

Using query parameters

Query parameters allow you to control what data is returned for a request. For example, a query parameter may let you specify the date range for a real estate markets price feed that are returned from the response.

For curl commands, add a ? to the end of the path, then append your query parameter name and value in the form parameter_name=value. Separate multiple query parameters with &.

For example, to get market details for New York with parcl_id 2900187 we need to supply the following required parameters to the /v1/place/{parcl_id}/price_feed endpoint:

start
end

Using a start date of 2023-01-01 and an end date of 2023-01-02, we form the following:

/price_feed/{parcl_id}/history/start=2023-01-01&end=2023-01-02

Bringing it all together into a curl command:

# GET /v1/price_feed/2900187/history
curl --request GET \
     --url 'https://api.realestate.parcllabs.com/v1/price_feed/2900187/history?start=2023-01-01&end=2023-01-02&order=desc' \
     --header 'Authorization: api_key' \
     --header 'accept: application/json'

Which returns:

{
  "parcl_id": 2900187,
  "name": "New York",
  "location_type": "MSA",
  "currency": "USD",
  "metric": "SQUARE_FOOT",
  "price_feed": [
    {
      "date": "2023-01-02",
      "price": 346.91
    },
    {
      "date": "2023-01-01",
      "price": 347.01
    }
  ]
}

Ready to supercharge your work? Check out these recipes to get going:

💣

Top Markets Summary

Open Recipe

😘

Marriage Demographics

Open Recipe

👹

Python Request as Pandas Dataframe

Open Recipe