API docs

Where to start: the nextSeq your last call returned. Leave it out, or send 0, to start from the beginning of the feed.

How many records a call returns, 1 to 1,000. The default is 200.

Only these counties: one or more ids from GET /v1/regions, separated by commas. Leave it out for every county your key covers.

Stable id of this business at this address. Upsert on it.

Venue ids served earlier that turned out to be this business. Delete them.

This venue's latest position in the feed.

When this place last changed, as an ISO 8601 timestamp.

The county the place is in, as an id from GET /v1/regions (kings-ny, bergen-nj, fairfield-ct, ...).

Trade name: a liquor record's DBA, else the health permit's name; the legal entity only when nothing else names the place (a company registration carries the company name only).

The company behind the place: the licensee on a liquor application or license, else the company a health permit names, else the company registered for it (in NYC, a company registered at the place's street address under a name sharing a word with the place's), else a health permit's name when that is a company (…LLC, …INC). null when no record names one.

Cuisine as the health department records it at the first inspection; NYC only.

Liquor license class (Restaurant, Food & Beverage Business, Cafe Liquor, ...).

Street address.

Town or city.

ZIP code.

Latitude (WGS 84). null when the address could not be placed on the map.

Longitude (WGS 84). null when the address could not be placed on the map.

NYC tax lot (10 digits), in the five boroughs.

The furthest step any record shows. See Stages below.

The date of the step in stage, YYYY-MM-DD. Which date it is depends on the stage (see Stages below).

true once a record shows the place serving; false while a record shows it not yet open; null when no record says.

Earliest date any record or linked permit shows, YYYY-MM-DD: how early the business was visible.

The public records that name this business.

Food-service building permits Townline holds for the property (the build-out, kitchen hood, sign), from 18 months before a record to 9 months after. A permit on a property shared with other new businesses appears only on the one it can be attributed to.

The business phone on the place's health permit (NYC only for now), as +1XXXXXXXXXX; null when no record lists one. Present only for keys with the contacts add-on.

The people behind the business, each once: those its own records name first (a license or permit held in a person's own name, a permit's operator, the owner on an inspection report), then those the state company register lists for its company (its chief executive, the person who receives its legal papers, its members and officers). People only, never a company, a registered agent or a law firm, and never a home address. Empty when no record or register names one.

What was at this street address before: food businesses the health department inspected there, last inspected before this business first showed (a company registered for it earlier doesn't count), other than this business. Newest first, at most two. NYC only for now; empty where none is listed, and where the address holds more than two other food businesses (a mall, food hall or office tower), since the address can't say which space this one took. Places drop off the health department's list some time after they close, so this reaches back a few years at most.

What the record is. See Record kinds below.

The kind of agency the record comes from: State liquor authority, Health department, Licensing agency, State company register or Building department.

Trade name (DBA) as the record gives it.

The legal name the record gives for who runs the place: the licensee, the permit holder or the registered company.

License class, establishment type, industry or cuisine, as the record gives it (Restaurant Liquor, Bakery, Delicatessen, Full-Service Restaurants, ...).

The status as the record gives it.

The address as the record gives it.

Application received, license preliminarily approved, or company registered, YYYY-MM-DD.

License or permit issued, finally approved, in effect or changed, YYYY-MM-DD; for a building_permit, the first permit naming the place. null while an application is pending, and for license lists that carry no dates: a record that is not presentAtLaunch is then dated by firstSeenAt.

First health inspection on record, YYYY-MM-DD: for a place this new, usually the pre-opening one (some agencies list only their latest inspection, or don't say whether it came before opening). null = not yet inspected.

When Townline first read this record.

Already on the agency's list when Townline started reading it, so firstSeenAt is not when it appeared.

When the record left the agency's list. A liquor application leaves the pending list when it is approved or withdrawn; the agency does not say which.

Stable id of this permit, the same one the permit feeds use.

The permit's date, YYYY-MM-DD: the date it was issued or, in some towns, the date it was applied for.

The type of permit, as the building department gives it.

The work description, with phone numbers and email addresses replaced by [phone removed] and [email removed].

The permit status, as the building department gives it.

The declared cost of the work in US dollars. null when the permit gives none.

The contractor named on the permit, with any phone number or email address cut out.

The address as the permit gives it.

bbl (same NYC tax lot), address (same street address and town), or nearby (same street address within ~150 m, town names differing).

As the record or register prints it: "RIVERA, PAT", "Pat Rivera".

What the record or register calls them: Licensee (a license held in a person's own name), Permit operator, Owner or Business owner (on an inspection report), Permit holder, Chief executive, Receives legal papers (the person a company names to receive its legal papers: for a small company usually an owner, sometimes its lawyer or accountant), or a company officer's title as the register gives it (Member, Manager, Officer, Director; Principal when it gives none).

Where the name comes from: the kind of agency whose record names them, or State company register.

Its name, as the health department lists it.

The health department's cuisine (Mexican, Coffee/Tea, ...).

Its earliest inspection on the health department's list, YYYY-MM-DD.

Its latest inspection, YYYY-MM-DD: about when it was last open.

Health department.

Where to start: the nextSeq your last call returned. Leave it out, or send 0, to start from the beginning of the feed.

How many records a call returns, 1 to 1,000. The default is 500.

Only these counties: one or more ids from GET /v1/regions, separated by commas. Leave it out for every county your key covers.

Stable id of this permit: p_ and 20 characters. Store permits by it. The change feed, search and GET /v1/permits/{id} use the same id.

This permit's position in the permit feed, as a string of digits. It never changes. Compare seq values as numbers, not as text.

The county the permit is in, as an id from GET /v1/regions (westchester-ny, kings-ny, fairfield-ct, ...).

The city, town, village or borough the work is in.

The type of permit, as the building department gives it (Building, Electrical, Plumbing, ...).

The work description, as the building department gives it. Phone numbers and email addresses in it are replaced with [phone removed] and [email removed].

The permit's current status, as the building department gives it. The wording varies from town to town.

The street address of the work, written the way the town writes it. When the permit gives none, we fill it in from the description or from property records where we can.

The property's tax block and lot, or parcel number, as the permit gives it. The format varies by area.

The permit's date, YYYY-MM-DD. Depending on the town, it's the date the permit was issued or the date it was applied for.

The declared cost of the work in US dollars, as the permit gives it.

The contractor named on the permit, with any phone number or email address cut out.

Who applied for the permit: often the contractor, but not always. Any phone number or email address is cut out.

The property owner as the permit names them or, when it names none, the owner of record from property tax records. Any phone number or email address is cut out.

The owner's mailing address.

true when the owner's mailing address is a different street address from the property's, false when it's the same. Left out when either one is missing.

The contractor license that best matches the contractor's name, from license lists in the same state: an active license first, then the latest expiry. See Licenses below.

The same for the applicant's name.

Latitude of the work site (WGS 84): from the permit when it gives one, otherwise from the address or parcel.

Longitude of the work site (WGS 84).

When we first found this permit, as an ISO 8601 timestamp.

When we last saw the status change, as an ISO 8601 timestamp. Left out until we see one.

When a field the change feed reports last changed on this permit, as an ISO 8601 timestamp. Left out if none has. It can be earlier than the change feed, which starts on October 28, 2026.

Each status change we've seen on this permit, oldest first; empty if none. See Status history below.

Our trade tags for the work, from the permit's type and description: up to 5, most confident first. See Trades below.

What the license is, as the license list names it (a home improvement or electrical contractor license, for example).

The license number.

The license's status as the license list gives it (Active, Expired, ...).

true when the license was active in our latest copy of the license list.

When the license expires, YYYY-MM-DD.

Stable id of this status change: e_ and 20 characters.

The status before the change. Left out when it was blank.

The status after the change. Left out when it became blank.

When we saw the change, as an ISO 8601 timestamp. This can be a few days after the town made it.

Trade id from GET /v1/trades: solar, roofing-siding-gutters, hvac-heating-cooling, electrical, plumbing-piping, pool-installation-service, ...

Trade name for display: Solar, Roofing / siding / gutters, ...

0.9 when the permit type or its fee breakdown names the trade, 0.75 when only the description does. 0.5 marks the general-contractor tag, given when nothing else matched.

The permit's id (p_...), the same one the permit feed gives it.

This change's position in the change feed. It's this feed's own cursor, not the permit's seq.

The county the permit is in.

changed, or deleted when the permit was taken down. A deleted event has no changes.

When we recorded the change, as an ISO 8601 timestamp.

Each changed field under its name on the permit record, as {"before": ..., "after": ...}. null means the field was empty before, or was cleared.

Only these counties: ids from GET /v1/regions, separated by commas. Leave it out for every county your key covers.

Only permits tagged with one of these trades: ids from GET /v1/trades, separated by commas.

single-family, multi-family, commercial or other, from property records. A permit whose property type we don't know matches none of them.

Only permits whose issuedDate is on or after, or on or before, this date (YYYY-MM-DD). Permits with no date are left out.

Only towns whose name contains this, such as Yonkers.

active (issued, work under way), review (applied for or in review), stopped (expired, stop-work order, on hold, void or revoked) or closed (finished or signed off). Any other value has to match the status exactly as the town gives it.

Words that must all appear in the address, description, names, town or permit type.

newest, by issuedDate (the default), or valuation, by declared cost.

desc (the default) or asc.

How many permits a call returns, 1 to 1,000. The default is 50.

The nextCursor your last page returned.

Facts about the property from assessor records, or from other property data where there's no assessor record. Which fields are filled varies by area.

The contractor's permits over the last 365 days, across every permit we hold. Given when the name matched a license or is clearly a business.

The same for the applicant.

Up to 10 other permits at the same property, newest first. In New York City, the other permits on the same building job.

The property's use class, as the area's records word it (Single family, Two family, Apartment building, ...).

true when the property houses more than one household. Left out otherwise.

The year the building was built.

The building's floor area in square feet.

The property's market value in US dollars from assessor records, estimated from the assessed value in some areas.

The last recorded sale price in US dollars, where the records carry sales.

The date of the last recorded sale, YYYY-MM-DD.

How many permits dated in the last 365 days name this business as applicant or contractor.

How many different towns those permits are in.

Their total declared cost in US dollars. Left out when none of them gives one.

The length of the window in days: 365.

That permit's id (p_...).

Its type of permit.

The name of its most confident trade tag.

Its current status.

Its date, YYYY-MM-DD, with the same meaning as issuedDate.

Its declared cost of work in US dollars.

true when it's dated within 45 days of this permit, which we count as the same job.

A parameter isn't valid, such as a limit over 1,000.

No key, a key we don't know, or a deleted key.

The key doesn't include this feed or county, or your account is off.

GET /v1/permits/{id} with an id we don't have.

Something failed on our side. Wait a minute and try the same call again.