Credits

Parcl Labs uses a credit-based (not API call-based) consumption model for its API. Read below to learn more about how credits work and how to manage them effectively.

What are Credits?

Credits are the unit of measure for consuming data through the Parcl Labs API. They allow you to manage how much data you retrieve and how you manage your API usage. Here's how credits work:

• Unit of measurement: Credits quantify how many items you retrieve within your API calls. 1 item = 1 credit.
• Metrics items: For API metrics, an item is defined as data associated with a specific date. This applies whether the timeframe is monthly, weekly, or daily, with each date retrieved counting as one item.

• Search items: 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.

Why use Credits?

We're committed to offering the best developer-friendly experience that extends to how you use and pay for our API. Here’s why we chose a credit system:

• Flexibility and precision: Whether you need the full history of an endpoint or just the latest updates, our credit system lets you pull exactly what you need. No overpaying for unused data—get precise control over the data you retrieve.
• Simplified API interaction: We eliminate arbitrary limits and pagination, making API calls straightforward. This simplicity lets you focus more on what matters—building your applications.

How to Manage Credits

You can define the number of items retrieved—and thus the credits used—through using API parameters such as limit, start_date, and end_date. Each item retrieved equals one credit.

Example of Managing Credits Through Parameters

Suppose you are interested in the monthly sales data for Fulton County, GA, for the first quarter of 2024. Here's how you could structure your API call to the Housing Event API endpoint:

GET /v1/market_metrics/{parcl_id}/housing_event_counts

Parameters:

• parcl_id: 5823604 (ID for Fulton County, GA)
• start_date: 2024-01-01
• end_date: 2024-03-31
• limit: Set to the number of months you want to retrieve data for, in this case, 3 for the three months of the first quarter.

In this example, you use the start_date and end_date parameters to specify the date range for Q1 2024 and set the limit to 3 to retrieve data for three specific dates within this period. This call will consume exactly three credits, aligning with the number of items retrieved.

curl -X GET 'https://api.parcllabs.com/v1/market_metrics/5823604/housing_event_counts?start_date=2024-01-01&end_date=2024-03-31&limit=3' \
     -H 'Authorization: {API_KEY}' \
     -H 'Accept: application/json'

📘

Before running the command:

Replace {API_KEY} with your actual API key.

Example Results:

{
  "parcl_id": 5823604,
  "property_type": "ALL_PROPERTIES",
  "items": [
    {
      "date": "2024-03-01",
      "sales": 1984,
      "new_listings_for_sale": 2860,
      "new_rental_listings": 12176
    },
    {
      "date": "2024-02-01",
      "sales": 2343,
      "new_listings_for_sale": 2551,
      "new_rental_listings": 10415
    },
    {
      "date": "2024-01-01",
      "sales": 1934,
      "new_listings_for_sale": 2391,
      "new_rental_listings": 12106
    }
  ],
  "total": 3,
  "limit": 3,
  "offset": 0,
}

How to Monitor Credits in the API Dashboard

You can easily monitor your credits through the API dashboard, which includes usage analytics that update in real time. Whether you're on a free or paid plan, your credits reset every month, helping you effectively manage your API usage.