Agents

The ZIP markets this agent works, blended

postapi.modelmatch.com/v1/agents/{id}/markets

Rank the ZIP markets one real-estate agent works, with volume, transaction counts and mean sale price per market, plus a weighted summary across the whole footprint. Optionally narrow to a ZIP list or a date window. REACH, NOT MARKET SHARE: an agent belongs to every market they touch — where their office is AND everywhere they have transacted — so one agent is counted in several markets at once. Per-market agent counts therefore over-sum: they cannot be added together, and dividing one into a total does not produce a market share. The only percentage returned, shareOfScope, is each market's share of this agent's volume across the scope requested and sums to 100 over that scope; there is no share-of-whole-book figure, because the transaction records carry no per-agent total to divide by. TWO COUNTS, ON PURPOSE: transactions counts transaction records; units counts the ones carrying a price, which are the records behind volume and avgSalePrice. Roughly half of an agent's records are priced, so dividing volume by transactions understates the average by about 2×. Figures are computed live from the agent's transaction records — an agent record carries no stored market rollup — and are ranked across their busiest ZIP markets. When a ZIP scope returns no markets, reach.presentInScope distinguishes 'works there, nothing closed in the window' from 'not present at all'. The summary also carries a Community Lending mix: what kind of neighborhood these markets are, weighted by the agent's activity in each. These are U.S. Census tract-level aggregates describing whole neighborhoods — never an individual, household or client attribute — and on this surface the basis is always the markets in scope, since an agent record carries no stored neighborhood rollup.

Authorization

x-api-keystringrequired

API key or OAuth token. See Authentication.

Path parameters

idstringrequired

Agent ID

Body application/json

dateRangeobject

Narrow the footprint to transactions inside this window. Omit for the agent's whole recorded history.

Show child attributes

fromstring

Inclusive lower bound on the transaction date.

tostring

Inclusive upper bound on the transaction date.

limitinteger

How many markets to return, ranked by volume descending (default 50). The summary is computed over the whole footprint BEFORE this truncation, so changing it never moves the totals or the average.

zipCodesstring[]

Narrow the footprint to these ZIP codes. 1–5 digits; a value that is not a ZIP is a 400 naming it, never a silently narrower result. Leading zeros may be omitted (1001 resolves to 01001).

Responses

200objectThe agent's blended market footprint

Show attributes

dataobjectrequired

Show child attributes

agentIdstringrequired

The canonical agent id these markets were computed for. May differ from the id sent if that id was a pre-merge one.

basisenumrequired

This is a REACH view. An agent belongs to every market they touch, so agent counts across markets over-sum and cannot be turned into a market share. See notes.

Options:reach

marketsobject[]required

Show child attributes

avgSalePricenumber | nullrequired

volume ÷ units — the mean priced sale in this market.

shareOfScopenumber | nullrequired

This market's share of the agent's volume ACROSS THE SCOPE REQUESTED, 0–100. It sums to 100 over the whole scope, so a page truncated by limit sums to less than 100 by exactly the share left out — the shares do not re-normalize to the page, because a number that moved every time you changed the page size would not be a share of anything stable. It is NOT this agent's share of the market itself, and it is not comparable across agents.

transactionsnumberrequired

Transaction records matched in this market. NOT every one of them carries a price — compare with units.

unitsnumber | nullrequired

Priced transaction records — the ones that contributed to volume, and the divisor behind avgSalePrice. Typically about half of transactions.

volumenumber | nullrequired

Total sale price across the priced records.

zipCodestring | nullrequired

The ZIP code this market is keyed by.

notesstring[]required

Plain-language caveats that apply to every figure above.

reachobjectrequired

Show child attributes

presentInScopeboolean | nullrequired

Whether this agent is present in the requested ZIP scope at all — by office location OR by any transaction on record. Null when no scope was requested. true with an empty markets array means the agent works that market but has no priced transaction there in the window, which is a different answer from false.

transactedInScopeboolean | nullrequired

Whether the scope produced any market with recorded transactions. Null when no scope was requested.

zipCodesRequestedstring[] | nullrequired

The normalized ZIP scope actually applied, or null when the caller asked for the whole footprint.

sourceobjectrequired

Show child attributes

modeenumrequired

Options:live

reasonsstring[]required

Why the figures were computed live from transaction records rather than read from a stored rollup.

summaryobjectrequired

Show child attributes

avgSalePricenumber | nullrequired

Volume-weighted mean priced sale across the footprint. Equal to volume ÷ units; NOT the average of the per-market averages, which drifts with market size.

communityLendingobject | nullrequired

The Community Lending mix of this footprint: the neighborhood characteristics of where the production landed, as percentages on a 0-100 scale. Null when nothing in scope resolved to a neighborhood — an absent block, never a row of zeroes, because 'no data' and '0%' are different answers. Read basis before comparing two responses. Values describe the U.S. Census tract (neighborhood) as a whole — tract-level aggregate statistics, never an individual, household or applicant attribute. Percentages are 0-100.

marketCountnumberrequired

How many placed markets contributed to this summary — the whole footprint inside the considered set, not the number of rows returned.

shareOfBooknullrequired

Always null on this surface. A share of an agent's whole book would need a per-agent total to divide by, and the transaction records carry none — publishing a partial sum as a total is the error this field exists to refuse.

transactionsnumberrequired

unitsnumber | nullrequired

unresolvedobjectrequired

Transactions whose market could not be placed. Held OUT of the summary and every ranking, and reported here so the coverage is stated rather than hidden.

volumenumber | nullrequired

400objectValidation error

401objectUnauthorized

403objectForbidden (authenticated, but missing required context — e.g. no active organization)

404objectNot found

413objectResponse payload too large — detail endpoint capped to fit Lambda response limits

503objectSearch timed out or the cluster is overloaded — retry after `Retry-After` seconds.

curl -X POST "https://api.modelmatch.com/v1/agents/<id>/markets" \
  -H "x-api-key: $MODEL_MATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zipCodes": [
      "77316",
      "77578"
    ],
    "limit": 123
  }'

import { createClient } from "@model-match/api";

const client = createClient({ apiKey: process.env.MODEL_MATCH_API_KEY });

const { data, error } = await client.agents.markets({
  path: {
    id: "<id>"
  },
  body: {
    zipCodes: [
      "77316",
      "77578"
    ],
    limit: 123
  }
});

import os
import requests

res = requests.post(
    "https://api.modelmatch.com/v1/agents/<id>/markets",
    headers={"x-api-key": os.environ["MODEL_MATCH_API_KEY"]},
    json={
        "zipCodes": [
            "77316",
            "77578"
        ],
        "limit": 123
    },
)
data = res.json()

200 response

{
  "data": {
    "agentId": "<string>",
    "basis": "reach",
    "markets": [
      {
        "avgSalePrice": 123.45,
        "shareOfScope": 123.45,
        "transactions": 123.45,
        "units": 123.45,
        "volume": 123.45,
        "zipCode": "<string>"
      }
    ],
    "notes": [
      "<string>"
    ],
    "reach": {
      "presentInScope": true,
      "transactedInScope": true,
      "zipCodesRequested": [
        "<string>"
      ]
    },
    "source": {
      "mode": "live",
      "reasons": [
        "<string>"
      ]
    },
    "summary": {
      "avgSalePrice": 123.45,
      "communityLending": {
        "affordableHousingTractPct": 123.45,
        "basis": "entityRollup",
        "coveredProductionPct": 123.45,
        "difficultDevelopmentAreaPct": 123.45,
        "distressedTractPct": 123.45,
        "floodHazardTractPct": 123.45,
        "incomeLevelMix": {
          "low": 123.45,
          "middle": 123.45,
          "moderate": 123.45,
          "upper": 123.45
        },
        "loansWithCommunityData": 123.45,
        "lowModIncomeTractPct": 123.45,
        "majorityMinorityTractPct": 123.45,
        "marketsInScope": 123.45,
        "marketsWithCommunityData": 123.45,
        "opportunityZonePct": 123.45,
        "predominantIncomeLevel": "low",
        "ruralTractPct": 123.45,
        "usdaEligibleTractPct": 123.45
      },
      "marketCount": 123.45,
      "shareOfBook": null,
      "transactions": 123.45,
      "units": 123.45,
      "unresolved": {
        "transactions": 123.45,
        "units": 123.45,
        "volume": 123.45
      },
      "volume": 123.45
    }
  }
}