Skip to main content
GET
Rank one lender by month, ZIP, city, county or cell
Early access: while the developer tier is in beta, the API serves this route to Investorlift’s team and trusted partners. Investorlift will restrict the route further before it opens to every key.
A page of lender ranking buckets, one per place the lender lent in, or one per month. Each bucket carries the lender’s loans there, and its rank and share among every lender of the market in that place and window. The page lists most loans first.

​
Use it when

“#1 in how many ZIPs?”, the lender card’s map at the cell grain, and the monthly series of one lender against the market. For the counts alone at the cell grain, use GET /v1/lenders/{id}/cells. For the leaderboard of a place, that is every lender ranked in one place, use GET /v1/lenders. For the profile’s own summary of it, read n_zips_ranked_first_24m, n_cities_ranked_first_24m and n_counties_ranked_first_24m on the Lender object.

​
How it works

  • group_by picks the grain: zip, city, county, cell (an H3 hexagon at res) or month, one bucket per calendar month, market-wide. You must send group_by. res beside any other grain is 400 validation_error, code res_without_cell. The key is the ZIP, the city, the county FIPS, the H3 index as hex, or the month as YYYY-MM.
  • period picks the window. 24m (the default) and 12m end on as_of. all is every dated instrument, and a calendar year YYYY is any year from 2002 to the slice year. A month YYYY-MM is one of the 36 that end on the slice month. A cell bucket serves 24m, 12m and all alone. Any other value is 400 validation_error, code period_not_served.
  • Under group_by=month the period is a span instead. all answers the 36 months. 24m and 12m answer the last 24 and 12, and YYYY answers its months. A year with none of the 36 is 400 validation_error, code period_not_served. YYYY-MM answers that one month. The response fills a month the lender recorded nothing in with n: 0, rank: null and share: 0, so the series is complete.
  • min_n is the lender’s own count in the bucket. Its default is the floor the profile’s ranked-first counts use. So a lender that is first in a ZIP with one loan among two is not “#1 there”. min_n=1 lists every place.
  • rank is among every lender of the market in the same place and window. Persons below the gate and placeholder names hold a slot, and the API breaks ties by volume, then id. share is the lender’s n over every lender’s instruments there. The registry build stores both from the same table the list reads. So a bucket’s share equals the row’s share on the list for that place. The list’s rank differs: it numbers its own rows, with persons and government hidden by default.
  • partial and floor. A bucket whose window ends after recordings_through is partial, for example the slice month or the slice year. A YYYY bucket before history_floor_year is floor, because the history already pushed out older mortgages on parcels with five filled slots.
  • Order is n descending then key ascending, keyset paged, so a lender’s every ZIP fits in one or two pages. Month buckets come oldest first. market= is necessary when the lender is in more than one loaded market, and 400 market_required says so.

​
Gotchas

  • A bucket’s rank counts persons and placeholders. A person who lends most in a ZIP holds rank 1 there. So a served lender can be first on the default list of that ZIP and second here. Both are right: they count different sets.
  • n_purchase_money and n_investor on a bucket read the deed link. They are null where the market’s build does not include the deed link. purchase_measured is false on the profile there.
  • A hex cell is the parcel’s, at res 8 about a third of a square mile and at res 7 about two. A cell string is the index any H3 library turns into an outline.
  • Every row is dated (meta.dated[]). The as_of is the slice date in meta.coverage[].lenders.as_of. require_current=true is 422 dated_refused. The API measures recency in a bucket against meta.coverage[].lenders.recordings_through.
  • A registry built before the place rankings answers 422 lenders_unavailable and names the route. The profile’s three ranked-first counts are null there. A market with no published registry answers the same. The API answers 400 invalid_id without the len_ prefix, 404 for an unknown id, and 400 invalid_cursor for a cursor from another query or an older dataset.
  • Since 0.17.0 the API follows old ids as on the profile route. For a merged id it answers 200 with meta.resolved_from and the current lender’s buckets. For a retired id it answers 410 gone. For an id never issued it answers 404 (Retired ids).
  • Not priced: the API charges no credits. Not a tool over MCP. The ranking row of godmode_lenders_top and godmode_lenders_nearby carries the other direction: the rank of every lender in one place.
Who is this lender? counts the ZIPs one lender leads.

Authorizations

​
Authorization
string
header
required

API key from the developer console (starts with zpka_). Create one at https://developers.investorlift.com/get-a-key.

Path Parameters

​
id
string
required

Lender id, len_ followed by 12 hex characters, for example len_d2028f0766fc. Take it from a search hit, a ranking row's lender.id or a parcel's financing block. The id is the same in every market and stable across data refreshes. The API follows an id from an earlier registry run to the current lender, and meta.resolved_from lists it. For a retired id with no successor, the API answers 410 gone.

Query Parameters

​
market
string

Market code, for example phx. The loaded markets are in meta.coverage[]. Send it only when the id exists in more than one loaded market. 400 market_required says so, and a lender has the same id in every market it lent in. Otherwise the API uses the id's own market.

Required string length: 1 - 16
​
group_by
enum<string>
required

The buckets that cut a lender's rankings. With month, the buckets are the market-wide calendar months, one row per month of the span, every month present. With zip, 5-digit ZIP codes. With city, city names in upper case, as the parcel table writes them. With county, 5-digit FIPS codes. With cell, H3 hexagons at the resolution res gives, 8 by default.

Available options:
month,
zip,
city,
county,
cell
​
res
enum<string>

H3 cell resolution with group_by=cell: 8 (the default) or 7. Resolution 8 has cells of about 0.3 square miles and resolution 7 of about 2 square miles. With any other group_by the API answers 400 validation_error, code res_without_cell.

Available options:
7,
8
​
period
string
default:24m

The period the buckets cover: 24m (the default), 12m, all, a calendar year YYYY, or a month YYYY-MM. YYYY is a year from 2002 to the slice year, and YYYY-MM is one of the 36 months up to the slice month. With group_by=cell it is a window alone. With group_by=month it is a span of months, every month present: all is the 36, 24m and 12m the last 24 and 12. Under group_by=month, YYYY is its months and YYYY-MM is that month. For any other value, or under group_by=month a year with none of the 36, the API answers 400 validation_error, code period_not_served.

Pattern: ^(12m|24m|all|\d{4}|\d{4}-(0[1-9]|1[0-2]))$
​
min_n
integer
default:10

Keep only buckets where the lender's own n is at least this, default 10. The ranked-first counts of the profile use the same floor. 1 lists every bucket it lent in. The filter does not apply to group_by=month, whose span the API serves whole with every month present.

Required range: 1 <= x <= 9007199254740991
​
limit
integer
default:100

Page size, 1-500 (default 100).

Required range: 1 <= x <= 500
​
cursor
string

Opaque cursor from page.next_cursor of the previous page. A change of query, sort, weights or data version invalidates it (400 invalid_cursor). Then restart from page 1.

Required string length: 1 - 4096
​
require_current
enum<string>
default:false

true refuses the request with 422 dated_refused while the registry's source, the financing slice, is a dated snapshot. The default false serves it, and meta.dated[] carries the lenders and financing blocks.

Available options:
true,
false

Response

The lender's buckets of one kind over the period, one page.

The lender's buckets of one kind over the period, one page.

​
data
object[]
required

The rows of this page.

​
page
object
required

Pagination: the page size, the rows returned and the cursor for the next page. Paged lists carry no total. The summary block does.

​
meta
object
required

Response metadata: when the API produced it, which markets it covers, and how fresh they are.