Parcl Labs API

https://docs.parcllabs.com/docs
Admin
The Parcl Labs API delivers real-time U.S. housing market insights, providing comprehensive data on...
Tokens:9,740
Snippets:56
Trust Score:9.1
Update:8 months ago
Show doc for...
Tokens:
Raw
### GET /v1/market_metrics/{parcl_id}/housing_event_counts

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

Retrieves the latest housing market activity for a specified market, including sales, new listings, and rental activity.

```APIDOC
## GET /v1/market_metrics/{parcl_id}/housing_event_counts

### Description
Retrieves the latest housing market activity for a specified market, including sales, new listings, and rental activity.

### Method
GET

### Endpoint
/v1/market_metrics/{parcl_id}/housing_event_counts

### Parameters
#### Path Parameters
- **parcl_id** (integer) - Required - The unique identifier for the market.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of data points to return. Defaults to 1.
- **offset** (integer) - Optional - The number of data points to skip. Defaults to 0.

### Request Example
```bash
curl -X GET "https://api.parcllabs.com/v1/market_metrics/2899845/housing_event_counts?limit=1&offset=0" \
  -H "Accept: application/json" \
  -H "Authorization: {API_KEY}"
```

### Response
#### Success Response (200)
- **parcl_id** (integer) - The identifier of the market.
- **property_type** (string) - The type of property.
- **items** (array) - An array of housing activity data points.
  - **date** (string) - The date of the data point.
  - **sales** (integer) - Completed home sales in the market.
  - **new_listings_for_sale** (integer) - New properties that came on the market.
  - **new_rental_listings** (integer) - New rental properties available.
  - **transfers** (integer) - Total ownership transfers.
- **total** (integer) - Total number of data points available.
- **limit** (integer) - The limit applied to the request.
- **offset** (integer) - The offset applied to the request.
- **links** (object) - Navigation links for retrieving additional data.
  - **first** (string) - Link to the first page of results.
  - **last** (string) - Link to the last page of results.
  - **self** (string) - Link to the current page of results.
  - **next** (string) - Link to the next page of results.
  - **prev** (string) - Link to the previous page of results.

#### Response Example
```json
{
  "parcl_id": 2899845,
  "property_type": "ALL_PROPERTIES",
  "items": [
    {
      "date": "2024-11-01",
      "sales": 13236,
      "new_listings_for_sale": 8478,
      "new_rental_listings": 17481,
      "transfers": 21544
    }
  ],
  "total": 71,
  "limit": 1,
  "offset": 0,
  "links": {
    "first": "https://api.parcllabs.com/v1/market_metrics/2899845/housing_event_counts?limit=1&offset=0",
    "last": "https://api.parcllabs.com/v1/market_metrics/2899845/housing_event_counts?limit=1&offset=70",
    "self": "https://api.parcllabs.com/v1/market_metrics/2899845/housing_event_counts?limit=1",
    "next": "https://api.parcllabs.com/v1/market_metrics/2899845/housing_event_counts?limit=1&offset=1",
    "prev": null
  }
}
```
```

--------------------------------

### Example API Response for Market Metrics

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

This JSON object represents a typical response from the Parcl Labs API when requesting housing market metrics. It includes the parcl_id, property type, a list of data items with dates and key housing statistics, pagination information, and navigation links for further data retrieval.

```json
{
  "parcl_id": 2899845,
  "property_type": "ALL_PROPERTIES",
  "items": [
    {
      "date": "2024-11-01",
      "sales": 13236,
      "new_listings_for_sale": 8478,
      "new_rental_listings": 17481,
      "transfers": 21544
    }
  ],
  "total": 71,
  "limit": 1,
  "offset": 0,
  "links": {
    "first": "https://api.parcllabs.com/v1/market_metrics/2899845/housing_event_counts?limit=1&offset=0",
    "last": "https://api.parcllabs.com/v1/market_metrics/2899845/housing_event_counts?limit=1&offset=70",
    "self": "https://api.parcllabs.com/v1/market_metrics/2899845/housing_event_counts?limit=1",
    "next": "https://api.parcllabs.com/v1/market_metrics/2899845/housing_event_counts?limit=1&offset=1",
    "prev": null
  }
}
```

--------------------------------

### Search Markets by Geographic Parameters

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

Allows searching for markets by specifying geographic scope (CITY, COUNTY, ZIP5, CBSA) and regional filters (region, state).

```APIDOC
## GET /v1/search/markets

### Description
Searches for markets based on specified geographic parameters such as state, city, county, zip code, CBSA, or region.

### Method
GET

### Endpoint
/v1/search/markets

### Query Parameters
- **state_abbreviation** (string) - Optional - The abbreviation of the state to filter by (e.g., 'CA').
- **location_type** (string) - Optional - The type of geographic boundary to search within (e.g., 'CITY', 'COUNTY', 'ZIP5', 'CBSA').
- **region** (string) - Optional - The region to filter by.

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

### Response
#### Success Response (200)
- **parcl_ids** (array of strings) - A list of parcl_ids matching the search criteria.

#### Response Example
```json
{
  "parcl_ids": [
    "7114_CA",
    "7115_CA"
  ]
}
```
```

--------------------------------

### Retrieve Market Metrics by parcl_id

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

Retrieves specific market metrics, such as housing stock, using a unique parcl_id.

```APIDOC
## GET /v1/market_metrics/{parcl_id}/housing_stock

### Description
Retrieves detailed housing stock metrics for a specific market identified by its `parcl_id`.

### Method
GET

### Endpoint
/v1/market_metrics/{parcl_id}/housing_stock

### Path Parameters
- **parcl_id** (string) - Required - The unique identifier for the market.

### Request Example
```bash
curl -X GET "https://api.parcllabs.com/v1/market_metrics/{parcl_id}/housing_stock" \
  -H "Accept: application/json" \
  -H "Authorization: {API_KEY}"
```

### Response
#### Success Response (200)
- **single_family** (integer) - The count of single-family homes in the market.
- **condo** (integer) - The count of condominiums in the market.
- **townhouse** (integer) - The count of townhouses in the market.

#### Response Example
```json
{
  "single_family": 15000,
  "condo": 5000,
  "townhouse": 2000
}
```
```

--------------------------------

### Search Markets API

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

Allows you to retrieve the parcl_id - the unique identifier for each market. This parcl_id is required for most other endpoints.

```APIDOC
## Search Markets API

### Description
Allows you to retrieve the `parcl_id` - the unique identifier for each market. This `parcl_id` is your gateway to the API and is required as a parameter in most other endpoints to access data about your selected market. Calls to this endpoint do not count against your credit limit.

### Method
GET

### Endpoint
/v1/search_markets

### Parameters
#### Query Parameters
- **query** (string) - Optional - A text-based query to search for a specific market (e.g., "New York City").
- **state** (string) - Optional - Filter markets by state.
- **county** (string) - Optional - Filter markets by county.
- **city** (string) - Optional - Filter markets by city.
- **zip_code** (string) - Optional - Filter markets by zip code.
- **msa** (string) - Optional - Filter markets by Metropolitan Statistical Area (MSA).

### Request Example
```bash
# Search for "New York City"
curl -X GET "https://api.parcllabs.com/v1/search_markets?query=New%20York%20City"

# Get all markets in California
curl -X GET "https://api.parcllabs.com/v1/search_markets?state=CA"
```

### Response
#### Success Response (200)
- **parcl_id** (integer) - The unique identifier for the market.
- **name** (string) - The name of the market.
- **geo_level** (string) - The geographic level of the market (e.g., CITY, ZIP_CODE, COUNTY, MSA).
- **state** (string) - The state the market is in.

#### Response Example
```json
[
  {
    "parcl_id": 12345,
    "name": "New York City",
    "geo_level": "MSA",
    "state": "NY"
  },
  {
    "parcl_id": 67890,
    "name": "Manhattan",
    "geo_level": "COUNTY",
    "state": "NY"
  }
]
```
```

--------------------------------

### Search Markets

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

Allows you to search for markets using a query term such as a city name, county, or zip code. It returns a list of matching markets with their associated details.

```APIDOC
## GET /v1/search/markets

### Description
Searches for markets based on a provided query term. This endpoint is useful for discovering geographic markets like cities, counties, or zip codes.

### Method
GET

### Endpoint
/v1/search/markets

### Parameters
#### Query Parameters
- **query** (string) - Required - The search term for the market (e.g., city name, county, zip code). URL-encode spaces (e.g., 'New York City' becomes 'New%20York%20City').
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.

#### Request Body
This endpoint does not accept a request body.

### Request Example
```bash
curl -X GET "https://api.parcllabs.com/v1/search/markets?query=New%20York%20City" \
  -H "Accept: application/json" \
  -H "Authorization: {API_KEY}"
```

### Response
#### Success Response (200)
- **items** (array) - A list of market objects matching the query.
  - **parcl_id** (integer) - The unique identifier for the market.
  - **country** (string) - The country the market is located in.
  - **geoid** (string) - The geographic identifier for the market.
  - **state_fips_code** (string or null) - The FIPS code for the state.
  - **name** (string) - The name of the market.
  - **state_abbreviation** (string or null) - The abbreviation for the state.
  - **region** (string or null) - The region the market belongs to.
  - **location_type** (string) - The type of geographic location (e.g., CITY, COUNTY).
  - **total_population** (integer) - The total population of the market.
  - **median_income** (integer) - The median income for the market.
  - **parcl_exchange_market** (integer) - Indicates if it's a Parcl exchange market (1 for yes, 0 for no).
  - **pricefeed_market** (integer) - Indicates if it has a price feed (1 for yes, 0 for no).
  - **case_shiller_10_market** (integer) - Indicates if it's part of the Case Shiller 10 index (1 for yes, 0 for no).
  - **case_shiller_20_market** (integer) - Indicates if it's part of the Case Shiller 20 index (1 for yes, 0 for no).
- **total** (integer) - The total number of markets found.
- **limit** (integer) - The limit applied to the results.
- **offset** (integer) - The offset applied to the results.
- **links** (object) - Pagination links.
  - **first** (string) - Link to the first page of results.
  - **last** (string) - Link to the last page of results.
  - **self** (string) - Link to the current page of results.
  - **next** (string or null) - Link to the next page of results.
  - **prev** (string or null) - Link to the previous page of results.

#### Response Example
```json
{
  "items": [
    {
      "parcl_id": 2900187,
      "country": "USA",
      "geoid": "35620",
      "state_fips_code": null,
      "name": "New York-Newark-Jersey City, Ny-Nj-Pa",
      "state_abbreviation": null,
      "region": null,
      "location_type": "CBSA",
      "total_population": 19908595,
      "median_income": 93610,
      "parcl_exchange_market": 0,
      "pricefeed_market": 1,
      "case_shiller_10_market": 1,
      "case_shiller_20_market": 1
    }
  ],
  "total": 6,
  "limit": 12,
  "offset": 0,
  "links": {
    "first": "https://api.parcllabs.com/v1/search/markets?query=New+York&offset=0",
    "last": "https://api.parcllabs.com/v1/search/markets?query=New+York&offset=0",
    "self": "https://api.parcllabs.com/v1/search/markets?query=New%20York",
    "next": null,
    "prev": null
  }
}
```
```

--------------------------------

### Make First API Call with cURL

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

This cURL command demonstrates how to make an initial API request to retrieve housing market activity for a specific parcl_id. It requires an API key for authorization and specifies parameters for limiting and offsetting results. The response includes market metrics like sales, new listings, and transfers.

```bash
curl -X GET "https://api.parcllabs.com/v1/market_metrics/2899845/housing_event_counts?limit=1&offset=0" \
  -H "Accept: application/json" \
  -H "Authorization: {API_KEY}"
```

--------------------------------

### Search Markets by Geographic Parameters (cURL)

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

This cURL command demonstrates how to search for markets using geographic parameters like state abbreviation and location type. It requires an API key for authentication and returns market identifiers (parcl_ids) for specified criteria.

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

--------------------------------

### Retrieve Market Housing Stock Metrics (cURL)

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

This cURL command shows how to retrieve housing stock metrics for a specific market using its unique parcl_id. It requires authentication with an API key and the parcl_id to fetch data such as housing counts for different property types.

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

--------------------------------

### Search Markets by Query Term using cURL

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

This snippet demonstrates how to search for geographic markets using a specific query term with the Parcl Labs API via cURL. It requires an API key and the query term, which should be URL-encoded. The command fetches market data, including `parcl_id`, name, and location details.

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

--------------------------------

### Housing Metrics: Multiple Datapoints Credit Example (JSON)

Source: https://docs.parcllabs.com/docs/credits

Illustrates the JSON response for multiple datapoints, showing that each datapoint corresponds to one credit used. This example highlights fetching historical data for a property.

```json
{
  "parcl_id": "5314518",
  "property_type": "SINGLE_FAMILY",
  "items": [
    {
      "date": "2024-05-20",
      "for_sale_inventory": 87
    },
    {
      "date": "2024-05-13",
      "for_sale_inventory": 86
    },
    {
      "date": "2024-05-06",
      "for_sale_inventory": 82
    }
  ],
  "total": 90,
  "limit": 3,
  "offset": 0
}
```

--------------------------------

### Parcl Labs API Market Search Response Structure

Source: https://docs.parcllabs.com/docs/parcl-labs-developer-quickstart-guide

This JSON object represents the response received after performing a market search using a query term. It contains a list of matching markets, each with details such as `parcl_id`, `name`, `country`, `location_type`, population, and income. It also includes pagination information.

```json
{
  "items": [
    {
      "parcl_id": 2900187,
      "country": "USA",
      "geoid": "35620",
      "state_fips_code": null,
      "name": "New York-Newark-Jersey City, Ny-Nj-Pa",
      "state_abbreviation": null,
      "region": null,
      "location_type": "CBSA",
      "total_population": 19908595,
      "median_income": 93610,
      "parcl_exchange_market": 0,
      "pricefeed_market": 1,
      "case_shiller_10_market": 1,
      "case_shiller_20_market": 1
    },
    {
      "parcl_id": 5372594,
      "country": "USA",
      "geoid": "3651000",
      "state_fips_code": "36",
      "name": "New York City",
      "state_abbreviation": "NY",
      "region": "MIDDLE_ATLANTIC",
      "location_type": "CITY",
      "total_population": 8622467,
      "median_income": 76607,
      "parcl_exchange_market": 1,
      "pricefeed_market": 1,
      "case_shiller_10_market": 0,
      "case_shiller_20_market": 0
    }
  ],
  "total": 6,
  "limit": 12,
  "offset": 0,
  "links": {
    "first": "https://api.parcllabs.com/v1/search/markets?query=New+York&offset=0",
    "last": "https://api.parcllabs.com/v1/search/markets?query=New+York&offset=0",
    "self": "https://api.parcllabs.com/v1/search/markets?query=New%20York",
    "next": null,
    "prev": null
  }
}
```

--------------------------------

### Housing Metrics: Single Datapoint Credit Example (JSON)

Source: https://docs.parcllabs.com/docs/credits

Demonstrates the JSON response structure when a single datapoint is requested, illustrating that this counts as one credit. This format is typical for housing metric data retrieval.

```json
{
  "parcl_id": "5314518",
  "property_type": "SINGLE_FAMILY",
  "items": [
    {
      "date": "2024-05-20",
      "for_sale_inventory": 87
    }
  ],
  "total": 90,
  "limit": 1,
  "offset": 0
}
```

--------------------------------

### API Error Codes Overview

Source: https://docs.parcllabs.com/docs/error-codes

This section details common error codes returned by the Parcl Labs API, explaining the cause of each error and providing steps to resolve it.

```APIDOC
## API Error Codes Overview

This document outlines the various error codes that may be returned by the Parcl Labs API. Each error code includes a description of the potential cause and recommended solutions to help you troubleshoot and resolve issues.

### Error Code Details

**401 - Invalid Token**
  *   **Cause**: Incorrect API key provided.
  *   **Solution**: Verify and copy the API key directly from the API Dashboard.

**403 - Usage Limit**
  *   **Cause**: Credit usage limit has been exceeded.
  *   **Solution**: Check your credit usage in the API Dashboard. Consider upgrading your account or contacting team@parcllabs.com for custom options.

**403 - Unauthorized**
  *   **Cause**: Insufficient permissions to access the requested data.
  *   **Solution**: Verify your permissions and ensure you are using the correct API endpoint. If the issue persists, contact support@parcllabs.com.

**404 - Data Not Found**
  *   **Cause**: The requested data could not be located.
  *   **Solution**: Verify the request URL and parameters, ensuring all identifiers and paths are correct. Check if the data exists for the queried timeframe, as it might be NULL.

**422 - Request Validation Error**
  *   **Cause**: The request contains invalid or missing parameters.
  *   **Solution**: Review your request for incorrect or missing fields. The API response will detail specific issues, such as incorrect property types or invalid date formats. Refer to the detailed guidance on 422 errors for specific troubleshooting steps.

**500 - Database Query Error**
  *   **Cause**: An internal error occurred during database processing.
  *   **Solution**: Retry the request. If the error persists, contact support@parcllabs.com for assistance.

**500 - Token Validation Error**
  *   **Cause**: An error occurred while validating the provided token.
  *   **Solution**: Verify the API token. If the token is correct and the error continues, contact support@parcllabs.com for further assistance.

### Further Assistance

If you are still experiencing issues, you can post on the [developer forum](https://docs.parcllabs.com/discuss) for help from the Parcl Labs team.
```

--------------------------------

### Credit Consumption Model

Source: https://docs.parcllabs.com/docs/credits

Explains the fundamental credit system for API data retrieval.

```APIDOC
## Credit Consumption Model

### Description
Parcl Labs utilizes a credit-based system where each credit corresponds to a single datapoint retrieved from the API. This model provides flexibility and control over data consumption.

### Housing Metrics
- **1 Credit = 1 Date of Data**
  - This applies regardless of whether you are requesting daily, weekly, or monthly aggregate metrics.
  - Example: Requesting one year of monthly metrics costs 12 credits, weekly metrics costs 52 credits, and daily metrics costs 365 credits.

### Property Data
- **1 Credit = 1 Property Returned**
  - The number of credits consumed is directly proportional to the number of properties included in the API response.

### Managing Credit Usage
- **Parameters**: Utilize parameters such as `start_date`, `end_date`, and `limit` to precisely control the amount of data retrieved, thereby managing credit expenditure.

### Tracking Credit Usage
- **API Responses**: Every API response includes an `account` object with `est_credits_used` and `est_remaining_credits` fields for real-time tracking.
- **Dashboard**: Monitor credit usage and balance in real-time via the [API dashboard](https://app.parcllabs.com/dashboard/api).

### Adding Credits
- **Free Tier**: The basic plan includes 1,000 free credits monthly, which reset every 30 days.
- **Upgrades**: Additional credits can be purchased and managed through the [API dashboard](https://app.parcllabs.com/dashboard/billing). Paid plans may offer features like credit rollover.
```

--------------------------------

### Track Credit Usage in API Responses (JSON)

Source: https://docs.parcllabs.com/docs/credits

This JSON snippet demonstrates how to track estimated credits used and remaining after an API request. The `account` object within the response provides real-time credit data.

```json
{
  "account": {
    "est_credits_used": 3,
    "est_remaining_credits": 997
  }
}
```
Tokens:
Raw