Quickstart

Learn how to create a Parcl Labs API key, make your first request, search markets, and start building. This quickstart guide is designed to help you access the Parcl Labs API and send your first API request. If you are an experienced developer and want to jump straight to the code, you can skip the quickstart and access our API reference.

Get Up and Running With the Parcl Labs API

1. Create a Parcl Labs account and access your API key
2. Make your first API call
3. Search a market
4. Check your usage
5. Start building with the API

1. Set Up Your API account

First, register for a free Parcl Labs account or sign in if you already have one.

Navigate to the dashboard to retrieve your API key. Click the API Key button to view your API Key.

Copy your key. Save this key in a secure location and do not share it with anyone.

2. Make Your First Request

Once you've secured your API key, you are set to begin interacting with the Parcl Labs API.

cURL is a widely used command-line tool that developers use to send requests to APIs. Here's an example cURL command you can copy and paste into your terminal. Execute it from your command line to retrieve the last month’s investor purchase to sale ratio for Chicago.

curl -X GET 'https://api.parcllabs.com/v1/investor_metrics/2899845/purchase_to_sale_ratio?limit=1&offset=0' \
-H 'Accept: application/json' \
-H 'Authorization: {API_KEY}'

📘

Before running the command:

Replace {API_KEY} with your actual API key.

What to expect when you run the command:

1. The cURL command sends a GET request to the Parcl Labs API, targeting the investor metrics purchase to sale ratio endpoint for the Chicago market, which is identified by "2899845".
2. The request includes a limit parameter set to 1, instructing the API to return the most recent month's data available.
3. The API processes the request and returns a JSON response that includes the purchase to sale ratio for the specified market.
4. The response will detail the investor purchase to sale ratio for the most recent month available for the Chicago market, identified by the parcl_id "2899845".

Example Results:

{
  "parcl_id": 2899845,
  "items": [
    {
      "date": "2024-02-01",
      "purchase_to_sale_ratio": 0.71
    }
  ],
  "total": 62,
  "limit": 1,
  "offset": 0,
  "links": {
    "first": "https://api.parcllabs.com/v1/investor_metrics/2899845/purchase_to_sale_ratio?limit=1&offset=0",
    "last": "https://api.parcllabs.com/v1/investor_metrics/2899845/purchase_to_sale_ratio?limit=1&offset=61",
    "self": "https://api.parcllabs.com/v1/investor_metrics/2899845/purchase_to_sale_ratio?limit=1",
    "next": "https://api.parcllabs.com/v1/investor_metrics/2899845/purchase_to_sale_ratio?limit=1&offset=1",
    "prev": null
  }
}

3. Search a Market

Following your first request, the next step is to explore the markets available through the Parcl Labs API. Our API covers every market in the US at any geographic level, including zip code, city, town, county, and Metropolitan Statistical Area (MSA) levels.

The search endpoint allows you to retrieve the parcl_id, the unique identifier for each market, which is essential for accessing market-level metrics endpoints that require the parcl_id.

Below, we explore two primary methods for using the search endpoint: by entering a specific text-based query, such as "New York City," or by applying geographic parameters to retrieve all parcl_ids that meet specific location criteria, like all cities within California.

A. Search Using a Query Term

The search query is the most straightforward method to discover markets using the Parcl Labs API. Here’s how you can craft and execute a search query effectively:

1. Craft your query: Input a specific name or term associated with the geographic area you are interested in. This could be a city name, a county, or even a zip code.
2. Executing the query-based search: Use the following cURL command to perform the search:

curl -X GET 'https://api.parcllabs.com/v1/search/markets?query={QUERY}' \
     -H 'Authorization: {API_KEY}' \
     -H 'Accept: application/json'

📘

Before running the command:

• Replace {API_KEY} with your actual API key
• Replace {QUERY} with your market of interest, ensuring that spaces in the query are URL-encoded (e.g., "New York City" becomes "New%20York%20City")

This command will return results for the query term (e.g., "New York City"), fetching the parcl_id(s) associated with this term.

B. Search Using Market Parameters

In addition to basic search term queries, the Parcl Labs API allows you to refine your search using specific geographic parameters. These parameters help narrow down the search results to more closely match your needs:

1. Geographic scope:
   • You can specify the type of geographic boundary for your search, such as CITY, COUNTY, ZIP5, or CBSA. This helps in pinpointing the exact level of data granularity you need.
2. Regional filtering:
   • The API allows filtering by region or state, facilitating searches that are constrained to specific areas of interest. For example, you can focus your search within a particular state or a broader federal region.
3. Executing the parameter-based search: Use the following cURL command to perform the search for markets in a specific state (CA) and location type (CITY):

curl -X GET 'https://api.parcllabs.com/v1/search/markets?state_abbreviation=CA&location_type=CITY' \
     -H 'Authorization: {API_KEY}' \
     -H 'Accept: application/json'

📘

Before running the command:

Replace {API_KEY} with your actual API key

This command will return results for all cities within the state of California, fetching all the parcl_ids associated with these cities.

C. Using parcl_id To Retrieve Market Metrics

Once you have the parcl_id for a specific market from your search results, you can use this identifier to request metrics about that market directly from the Parcl Labs API.

How to Use the parcl_id:

• Insert the parcl_id into the API request path: Use the parcl_id as an API path parameter to access specific data endpoints, such as housing stock, market prices, rental yields, or investor metrics.

Example Command to Retrieve Metrics:

To get information about the housing stock for a particular market, you can use the following command:

curl -X GET 'https://api.parcllabs.com/v1/market_metrics/{parcl_id}/housing_stock' \
     -H 'Authorization: {API_KEY}' \
     -H 'Accept: application/json'

📘

Before running the command:

• Replace {API_KEY} with your actual API key
• Replace {parcl_id} with the actual parcl_id obtained from your search

Using the parcl_id, this command retrieves data on the market's housing stock, including counts of single-family homes, condos, and townhouses.

Congrats! You've successfully navigated key functionalities of the API: you've performed market searches to identify parcl_ids and accessed core housing market metrics, such as housing stock and investor purchase-to-sale ratios.

4. Check Your Usage

Keep track of your API usage in real-time by visiting the Parcl Labs dashboard. Parcl Labs uses a credit-based consumption model for its API, If you've followed the Quickstart from start to finish, you'll notice your credit usage metrics updated accordingly:

It's important to note that calls to the search endpoint (/v1/search/markets) do not count against your credit limit. We want you to easily find the markets you need to kickstart your analysis without impacting your available credits. For more information on what these metrics mean and how to manage your consumption efficiently, refer to our credits guide.

5. Start Building

Now that you have made your first Parcl Labs API request, it's time to explore what else is possible:

1. Learn by building with our Examples Repository. We've open-sourced our research to help you easily recreate analysis and data visualizations with just a few clicks
2. Install the Parcl Labs Python SDK to efficiently pull market data at scale
3. Review the API Reference to see the full extent of endpoints available in the Parcl Labs API
4. Get inspired by reviewing our research
5. Provide feedback or ask questions in our Developer Forum