API Documentation

Overview

The API is a read-only JSON REST API. You send authenticated GET requests with query-string filters and receive a predictable JSON envelope. Every data endpoint lives under the base URL above.

• Format: JSON over HTTPS. All responses use a consistent { success, data } envelope.
• Auth: a Bearer API key on every data request.
• Scope: you can query the data types and states included in your subscription. Requests outside that scope are declined.
• Limits: a per-minute rate limit plus your plan's request quota.

Authentication

Authenticate by sending your API key as a Bearer token in the Authorization header on every request to a protected endpoint:

Authorization: Bearer YOUR_API_KEY

Keys are issued with your subscription from your account dashboard. Keep them secret — a key carries your plan's access and quota. If a key is missing or malformed you'll get 401; if it's invalid or inactive you'll get 403.

Quick start

Three steps to your first response:

1. Get your key from your account dashboard after subscribing.
2. Call an endpoint with your filters and the Bearer header.
3. Read the envelope — your results are in data, totals in meta.

A first request for FSBO listings in Texas:

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/properties?pdm_state=TX&pdm_data_type=fsbo&pdm_per_page=5' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Requests & headers

All data endpoints are GET requests. Filters are passed as URL query parameters. Recommended headers:

CORS: the API is cross-origin friendly. It echoes the request Origin, allows the Authorization header, answers OPTIONS preflight, and exposes the rate-limit headers (X-RateLimit-*, Retry-After) to browser clients. Cookies/credentials are not used.

Unknown parameters are rejected. Every endpoint declares the exact parameters it accepts; sending anything else returns 400. Stick to the documented filters.

Rate limits

Requests are rate limited per key, per minute. Every pdm/v1 response includes the current state in headers:

Exceed the limit and you receive 429 with code rest_rate_limited. Honor Retry-After before retrying. This minute-window limit is separate from your plan's overall quota described next.

Quotas & entitlements

Two independent limits apply:

• Rate limit — short-term burst protection (per minute, above).
• Plan quota — the total number of data requests your subscription allows, and which data types and states it covers. Each successful data request consumes one slot (automatically refunded if the upstream source fails).

Two parameters are easy to confuse but mean different things:

Response format

Every response uses one of three envelope shapes.

Single object

{
  "success": true,
  "data": { "...": "a single resource" }
}

List

Results are in data (an array); pagination and totals are in meta.

{
  "success": true,
  "data": [ { "...": "item" }, { "...": "item" } ],
  "meta": {
    "total": 1842,
    "page": 1
  }
}

Error

{
  "success": false,
  "error": {
    "code": "rest_forbidden",
    "message": "Invalid or inactive API Key",
    "status": 403
  }
}

Pagination

Control paging with pdm_page and pdm_per_page. The total result count comes back in meta.total, so the number of pages is ceil(meta.total / pdm_per_page).

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/properties?pdm_state=FL&pdm_data_type=for_sale&pdm_page=2&pdm_per_page=50' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Errors

Errors return the error envelope with a machine-readable code, a message, the HTTP status, and optional details.

Filter parameters

These apply to the list endpoints (properties and agents). Price/size filters are ignored for agents.

List properties

Search property listings with the filter parameters. Requires authentication and consumes one quota slot. Returns a paginated list.

Example request

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/properties?pdm_state=TX&pdm_data_type=fsbo&pdm_beds=3&pdm_min_price=200000&pdm_per_page=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example response

{
  "success": true,
  "data": [
    {
      "property_id": "123456789",
      "list_price": 329000,
      "address": "123 Main St, Austin, TX 78701",
      "beds": 3,
      "baths": 2,
      "sqft": 1840,
      "status": "for_sale"
    }
  ],
  "meta": { "total": 1842, "page": 1 }
}

Get a property

Fetch a single property by its property_id. Requires authentication.

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/properties/123456789' \
  -H 'Authorization: Bearer YOUR_API_KEY'

List agents

Search agent records. Accepts the same schema as properties (location and paging filters apply; price/size filters are ignored). Requires authentication and consumes one quota slot.

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/agents?pdm_state=CA&pdm_city=San%20Diego&pdm_per_page=25' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Get an agent

Fetch a single agent by id. Requires authentication.

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/agents/AGENT_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Suggestions

Lightweight location autocomplete, handy for search boxes. Requires authentication.

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/suggestions?q=aus' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Account

Returns the account, plan, and current usage tied to your key. Requires authentication but does not consume a data quota slot — useful for showing remaining quota in your own dashboard.

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/me' -H 'Authorization: Bearer YOUR_API_KEY'

Analytics

Usage analytics for your key (request volume over time). Requires authentication; no quota consumed.

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/analytics' -H 'Authorization: Bearer YOUR_API_KEY'

Preview (no auth)

Public, unauthenticated endpoints for testing and free-tier front-ends. No key required. They accept the same filters but are capped: up to 5 pages, 20 results per page, and a total of 100. They're the fastest way to see the live response shape.

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/preview/properties?pdm_state=NY&pdm_per_page=5'

Health

Public status probe for uptime monitoring. No auth, no quota, no upstream calls.

{
  "status": "ok",
  "version": "x.y.z",
  "timestamp": "2026-06-02T00:00:00Z",
  "checks": { "db": "ok" }
}

Code examples

A typical authenticated list request in three languages.

curl -s 'https://buyrealestatedata.com/wp-json/pdm/v1/properties?pdm_state=TX&pdm_data_type=fsbo&pdm_per_page=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const res = await fetch(
  'https://buyrealestatedata.com/wp-json/pdm/v1/properties?' + new URLSearchParams({
    pdm_state: 'TX',
    pdm_data_type: 'fsbo',
    pdm_per_page: '20',
  }),
  { headers: { Authorization: 'Bearer ' + API_KEY } }
);
const json = await res.json();
if (!json.success) throw new Error(json.error.message);
console.log(json.meta.total, json.data);

<?php
$url = 'https://buyrealestatedata.com/wp-json/pdm/v1/properties?' . http_build_query([
    'pdm_state'     => 'TX',
    'pdm_data_type' => 'fsbo',
    'pdm_per_page'  => 20,
]);
$res = wp_remote_get($url, [
    'headers' => ['Authorization' => 'Bearer ' . $api_key],
    'timeout' => 30,
]);
$body = json_decode(wp_remote_retrieve_body($res), true);
if (empty($body['success'])) {
    // handle $body['error']
}
$listings = $body['data'];
$total    = $body['meta']['total'];

Troubleshooting

I'm getting 401 Missing Authorization Header

Add the header Authorization: Bearer YOUR_API_KEY. Some HTTP clients strip it on redirects — send it explicitly.

I'm getting 403 on every request

Either the key is inactive, your quota is used up, or you're requesting a pdm_data_type/pdm_state outside your plan. Check /me for your entitlements and remaining quota.

I'm getting 400

A parameter is unknown or invalid. Only the documented filters are accepted, and pdm_state must be a 2-letter code.

I'm getting 429

You exceeded the per-minute limit. Wait the number of seconds in the Retry-After header, then retry. Watch X-RateLimit-Remaining to pace requests.

data is empty

Your filters may be too narrow, or you're on a preview/trial response (capped at 100 results). Broaden the filters or confirm your plan covers the requested type and state.