---
title: "Compare explicit provider regions at one common period"
method: GET
path: "/api/v1/market/zillow/compare"
tags: ["Market"]
---

# Compare explicit provider regions at one common period

`GET /api/v1/market/zillow/compare`

## Request

- Base URL: `https://propraven.com`
- URL: `https://propraven.com/api/v1/market/zillow/compare`
- Auth: HTTP bearer

Requires API-key or first-party session authentication and a current account in the default-off server cohort. Valid current membership does not require a new paid subscription. Existing API quotas still apply. Responses are private, no-store. Unknown and repeated query parameters are rejected. This contract does not indicate source activation, deployment or an SDK release. Use-specific, unexpired reviewed Zillow rights are checked before parcel resolution or repository/cache access. Denied/unknown rights return explicit unavailable metric values, not substitute data. Each metric exposes actual regional geography/variant and freshness; regional values do not become parcel estimates or residual inputs. Up to five distinct region IDs use one dataset/accepted snapshot and common month. First ID is the reference. Value gaps retain a missing reason; incompatible regions are not converted to comparable parcel data. Alternatively provide parcel_id, metric and period (optional window_months) instead of dataset_key and region_ids. Property geography is resolved only by the server. County/metro/national comparisons require compatible metric definitions, units and variants, one requested month and an explicit captured acceptance cutoff. Each dataset retains its own snapshot provenance. Missing mappings, permissions and variants remain unavailable; mixed query forms are rejected.

## Query parameters

- `dataset_key` string
- `region_ids` string
- `period` string, required
- `as_of` string, date-time
- `use` 'display' | 'agent' | 'export'
- `parcel_id` string
- `metric` 'zori' | 'zhvi' | 'inventory' | 'price_cut_share' | 'median_days_to_pending'
- `window_months` '12' | '36' | '60'

## Response `200`

Authorized result; unavailable/partial/stale states are explicit within the response. No live coverage is implied by this contract.

- union
  - ZillowComparison: Up to five explicit provider regions at a common period/accepted snapshot. Gaps have a nullable value and explicit nullable reason; missing values are not zero.
    - `schemaVersion` 'zillow-market-v1', required
    - `datasetKey` string, required
    - `period` string, required
    - `referenceRegionId` string, required
    - `metrics` object[], required
      - `rights` object, nullable, required
        - `version` string, required
        - `evidenceUrl` string, nullable, required
        - `expiresAt` string, nullable, required
      - `metric` 'zori' | 'zhvi' | 'inventory' | 'price_cut_share' | 'median_days_to_pending', required
      - `status` 'available' | 'unavailable', required
      - `reason` string, nullable, required
      - `definition` string, required
      - `unit` 'usd' | 'usd_per_month' | 'count' | 'fraction' | 'days', required
      - `value` number, nullable, required
      - `period` string, nullable, required
      - `variant` object, nullable, required
        - `datasetKey` string, required
        - `registryVersion` integer, required
        - `universe` string, required
        - `frequency` 'monthly', required
        - `smoothing` 'smoothed', required
        - `seasonalAdjustment` 'sa' | 'not_stated', required
      - `geography` object, nullable, required
        - `providerId` string, required
        - `name` string, required
        - `type` 'country' | 'msa' | 'county' | 'zip', required
      - `mapping` object, nullable, required
        - `method` 'postal_zip' | 'county_fips' | 'verified_crosswalk' | 'explicit_provider_region', required
        - `version` string, required
        - `source` string, required
        - `fallbackReason` string, nullable, required
      - `snapshot` object, nullable, required
        - `id` string, required
        - `sha256` string, required
        - `retrievedAt` string, date-time, required
        - `acceptedAt` string, date-time, required
        - `latestPeriod` string, required
        - `stale` boolean, required
      - `annualChange` object, nullable, required
        - `value` number, nullable, required
        - `unit` 'percent' | 'percentage_points' | 'days', required
        - `reason` string
      - `monthlyChange` object, nullable, required
        - `value` number, nullable, required
        - `unit` 'percent' | 'percentage_points' | 'days', required
        - `reason` string
      - `rentAcceleration` object, nullable, required
        - `value` number, nullable, required
        - `unit` 'percent' | 'percentage_points' | 'days', required
        - `reason` string
      - `points` object[], required
        - `period` string, required
        - `value` number, nullable, required
      - `sourceUrl` string, required
      - `attribution` string, required
    - `gaps` object[], required
      - `regionId` string, required
      - `value` number, nullable, required
      - `reason` string, nullable, required
      - `unit` 'days' | 'percentage_points', required
  - ZillowPropertyComparison
    - `schemaVersion` 'zillow-property-comparison-v1', required
    - `canonical_id` string
    - `metric` 'zori' | 'zhvi' | 'inventory' | 'price_cut_share' | 'median_days_to_pending', required
    - `period` string, required
    - `asOf` string, date-time, required
    - `reference` 'county' | 'metro' | 'national', nullable, required
    - `items` object[], required
      - `level` 'county' | 'metro' | 'national', required
      - `datasetKey` string, nullable, required
      - `result` object, required
        - `rights` object, nullable, required
          - `version` string, required
          - `evidenceUrl` string, nullable, required
          - `expiresAt` string, nullable, required
        - `metric` 'zori' | 'zhvi' | 'inventory' | 'price_cut_share' | 'median_days_to_pending', required
        - `status` 'available' | 'unavailable', required
        - `reason` 'missing_period' | 'nonpositive_denominator' | 'non_finite_result' | 'not_applicable' | 'mapping_unavailable' | 'no_coverage' | 'suppressed' | 'historical_vintage_unavailable' | 'rights_unavailable' | 'disabled' | 'incompatible_variant', nullable, required
        - `definition` string, required
        - `unit` 'usd' | 'usd_per_month' | 'count' | 'fraction' | 'days', required
        - `value` number, nullable, required
        - `period` string, nullable, required
        - `variant` object, nullable, required
          - `datasetKey` string, required
          - `registryVersion` integer, required
          - `universe` string, required
          - `frequency` 'monthly', required
          - `smoothing` 'smoothed', required
          - `seasonalAdjustment` 'sa' | 'not_stated', required
        - `geography` object, nullable, required
          - `providerId` string, required
          - `name` string, required
          - `type` 'country' | 'msa' | 'county' | 'zip', required
        - `mapping` object, nullable, required
          - `method` 'postal_zip' | 'county_fips' | 'verified_crosswalk' | 'explicit_provider_region', required
          - `version` string, required
          - `source` string, required
          - `fallbackReason` string, nullable, required
        - `snapshot` object, nullable, required
          - `id` string, required
          - `sha256` string, required
          - `retrievedAt` string, date-time, required
          - `acceptedAt` string, date-time, required
          - `latestPeriod` string, required
          - `stale` boolean, required
        - `annualChange` object, nullable, required
          - `value` number, nullable, required
          - `unit` 'percent' | 'percentage_points' | 'days', required
          - `reason` 'missing_period' | 'nonpositive_denominator' | 'non_finite_result' | 'not_applicable' | 'mapping_unavailable' | 'no_coverage' | 'suppressed' | 'historical_vintage_unavailable' | 'rights_unavailable' | 'disabled' | 'incompatible_variant'
        - `monthlyChange` object, nullable, required
          - `value` number, nullable, required
          - `unit` 'percent' | 'percentage_points' | 'days', required
          - `reason` 'missing_period' | 'nonpositive_denominator' | 'non_finite_result' | 'not_applicable' | 'mapping_unavailable' | 'no_coverage' | 'suppressed' | 'historical_vintage_unavailable' | 'rights_unavailable' | 'disabled' | 'incompatible_variant'
        - `rentAcceleration` object, nullable, required
          - `value` number, nullable, required
          - `unit` 'percent' | 'percentage_points' | 'days', required
          - `reason` 'missing_period' | 'nonpositive_denominator' | 'non_finite_result' | 'not_applicable' | 'mapping_unavailable' | 'no_coverage' | 'suppressed' | 'historical_vintage_unavailable' | 'rights_unavailable' | 'disabled' | 'incompatible_variant'
        - `points` object[], required
          - `period` string, required
          - `value` number, nullable, required
        - `sourceUrl` string, required
        - `attribution` string, required
      - `gap` object, required
        - `value` number, nullable, required
        - `unit` 'percent' | 'percentage_points' | 'days', required
        - `reason` 'missing_period' | 'nonpositive_denominator' | 'non_finite_result' | 'not_applicable' | 'mapping_unavailable' | 'no_coverage' | 'suppressed' | 'historical_vintage_unavailable' | 'rights_unavailable' | 'disabled' | 'incompatible_variant'

## Other responses

- `400`: Invalid, unknown or duplicate parameters; invalid time, source key or scenario assumptions.
- `401`: Authentication required, or supplied credential invalid. A rejected bearer does not fall back to a session.
- `402`: Existing API-key monthly quota exceeded; this feature adds no paid SKU.
- `403`: Access forbidden by an upstream account policy.
- `404`: Feature disabled, current account outside cohort, or requested retained object/parcel unavailable. Other creators' objects are not disclosed.
- `429`: Existing API or concurrent-request limit exceeded.
- `500`: Unexpected service failure; internal details are withheld.
- `504`: Database query timeout.

---

[API](https://skmtc.dev/propraven/apis/propraven-api.md) · [All operations](https://skmtc.dev/propraven/apis/propraven-api/llms.txt) · [OpenAPI document](https://skmtc.dev/propraven/apis/propraven-api/revisions/37f8158c4eda?raw)