Quickstart

Pull real time real estate data in under 3 minutes

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",
    "country_code": "USA",
    "tickers": [
      {
        "key": "parcl_labs",
        "symbol": "USA.COUNTY.NY.BKL"
      },
      {
        "key": "media",
        "symbol": ".PLABS.COUNTY.BKL"
      }
    ]
  },
  {
    "parcl_id": 5822484,
    "location_type": "COUNTY",
    "name": "Manhattan",
    "state": "NY",
    "state_name": "New York",
    "state_fips_code": "36",
    "census_region": "Middle Atlantic",
    "country_code": "USA",
    "tickers": []
  },
  {
    "parcl_id": 2900187,
    "location_type": "MSA",
    "name": "New York",
    "state": "NY",
    "state_name": "New York",
    "state_fips_code": "36",
    "census_region": "Middle Atlantic",
    "country_code": "USA",
    "tickers": [
      {
        "key": "parcl_labs",
        "symbol": "USA.MSA.NYC"
      },
      {
        "key": "media",
        "symbol": ".PLABS.METRO.NYC"
      }
    ]
  },
  {
    "parcl_id": 5372594,
    "location_type": "CITY",
    "name": "New York",
    "state": "NY",
    "state_name": "New York",
    "state_fips_code": "36",
    "census_region": "Middle Atlantic",
    "country_code": "USA",
    "tickers": [
      {
        "key": "parcl_labs",
        "symbol": "USA.CITY.NY.NYC"
      },
      {
        "key": "media",
        "symbol": ".PLABS.CITY.NYC"
      }
    ]
  }
]

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,
  "limit": 30,
  "offset": 0,
  "total": 10,
  "previous": null,
  "next": null,
  "name": "Las Vegas",
  "location_type": "MSA",
  "currency": "USD",
  "metric": "SQUARE_FOOT",
  "price_feed": [
    {
      "date": "2023-08-31",
      "price": 241.73
    },
    {
      "date": "2023-08-30",
      "price": 241.73
    },
    {
      "date": "2023-08-29",
      "price": 241.78
    },
    {
      "date": "2023-08-28",
      "price": 241.65
    },
    {
      "date": "2023-08-27",
      "price": 241.52
    },
    {
      "date": "2023-08-26",
      "price": 241.52
    },
    {
      "date": "2023-08-25",
      "price": 241.5
    },
    {
      "date": "2023-08-24",
      "price": 241.49
    },
    {
      "date": "2023-08-23",
      "price": 241.35
    },
    {
      "date": "2023-08-22",
      "price": 241.1
    }
  ]
}

📘

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. In this example, we'll use python and the requests library to get price feeds for every market in the state of 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 AreaParcl Labs Market ID
San Francisco2900336
Los Angeles2900078
New York2900187
Phoenix2900245
San Diego2900332
Seattle2900353
Chicago2899845
Miami2900128
Boston2899625
Denver2899750
Atlanta2887280
Las Vegas2900049
Washington, DC2900475
Tampa2900417
Portland2900266
Minneapolis2900137
Charlotte2899841
Detroit2899753
Cleveland2899654

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
    }
  ]
}

Working with Paginated Endpoints

Historical endpoints, such as v1/price_feed/{parcl_id}/history and v1/financials/{parcl_id}/history are paginated. This means that each request made to a paginated endpoint only returns a subset of the available data. Paginated endpoints include two additional parameters, limit, which specifies the number of records to return, and offset, which specifies the number of records to bypass before returning data. Limit maximums are set at the endpoint-level.

Here's an example request for the v1/price_feed/{parcl_id}/history endpoint, using the New York MSA parcl_id. In the request, limit is set to 7, offset is set to 30, and the order is desc. This allows us to bypass the 30 most recent records.

curl --request GET \
     --url 'https://api.realestate.parcllabs.com/v1/financials/2900187/history?order=desc&offset=30&limit=12' \
     --header 'Authorization: api_key' \
     --header 'accept: application/json'

This request returns the following data. The response metadata for paginated endpoints also includes additional parameters:

  • limit - The limit passed into the request
  • offset - The offset passed into the request
  • total - The total number of records for the provided parcl_id in this endpoint
  • previous - The request to get the previous set of records, based on the supplied parameters. If there are no previous records, this value will be null
  • next - The request to get the next set of records, based on the supplied parameters. If there are no additional records, this value will be null
{
  "parcl_id": 2900187,
  "limit": 7,
  "offset": 30,
  "total": 366,
  "previous": "https://api.realestate.parcllabs.com/v1/price_feed/2900187/history?offset=23&limit=7&order=desc&start=2023-01-02&end=2024-01-02",
  "next": "https://api.realestate.parcllabs.com/v1/price_feed/2900187/history?offset=37&limit=7&order=desc&start=2023-01-02&end=2024-01-02",
  "name": "New York",
  "location_type": "MSA",
  "currency": "USD",
  "metric": "SQUARE_FOOT",
  "price_feed": [
    {
      "date": "2023-12-03",
      "price": 379.54
    },
    {
      "date": "2023-12-02",
      "price": 379.22
    },
    {
      "date": "2023-12-01",
      "price": 377.92
    },
    {
      "date": "2023-11-30",
      "price": 376.48
    },
    {
      "date": "2023-11-29",
      "price": 376.42
    },
    {
      "date": "2023-11-28",
      "price": 376.43
    },
    {
      "date": "2023-11-27",
      "price": 376.52
    }
  ]
}

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


What’s Next