howfar · api docs

endpoint

GET https://howfar.dev/events header X-API-Key: <your key>

parameters

all optional. combine freely.

when

natural-language date, resolved server-side: this halloween · this weekend · tonight · tomorrow · a weekday. explicit from/to override it.

from

YYYY-MM-DD, on/after this event-local date (a Sat 11pm party counts as Saturday).

to

YYYY-MM-DD, on/before this event-local date.

location

city substring, e.g. new york. NYC-only today, here so queries read the same as more cities land.

neighborhood

blanket sub-area: a granular hood (lower east side, bushwick) or, in NYC, a borough name (brooklyn). matches either field, and not every city has boroughs.

borough

exact NYC bucket if you want it precise: Manhattan · Brooklyn · Queens · Bronx · Staten Island.

genre

substring, e.g. afrobeats, amapiano, house.

max_price

dollars. compares the all-in price when the source shows one, else the advertised price. free and unknown-price events stay included.

source

partiful · posh · dice · web.

sold_out

false hides sold-out events, true returns only those.

limit

max rows. default 200, cap 1000.

example

curl -H "X-API-Key: $KEY" \ "https://howfar.dev/events?location=new+york&when=this+weekend&neighborhood=brooklyn&genre=afrobeats&max_price=30"

response

{
  "events": [{
    "source": "partiful", "title": "...", "venue": "...",
    "neighborhood": "Bushwick", "borough": "Brooklyn", "city": "New York",
    "startsLocal": "2026-11-01T01:00:00-04:00", "localDate": "2026-10-31",
    "priceCents": 2000, "priceIncludesFees": false, "genre": "afrobeats",
    "soldOut": false, "url": "https://partiful.com/e/...",
    "sources": [
      {"source": "partiful", "url": "https://partiful.com/e/..."},
      {"source": "dice", "url": "https://dice.fm/event/..."}
    ],
    "lastChecked": "2026-10-31T09:00:00Z"
  }],
  "count": 1
}

every number either came from the source or is labeled as ours. localDate / startsLocal are the event's own wall-clock (ET for NYC), and date filters use localDate. a set that starts after midnight counts as the night before: a party at 1am on Nov 1 has a localDate of Oct 31, so "friday night" and "this weekend" catch the after-hours sets you would expect. an event posted on multiple platforms is one row, and every link lands in sources (url is the primary one).

prices

priceCents

minimum advertised price at the link, what a buyer sees going in.

priceIncludesFees

what that number means per source: true (dice advertises all-in), false (posh advertises face), null (unknown).

priceFaceCents

price before fees, filled only when the source shows it.

priceAllInCents

what the buyer actually pays, filled only when the source shows it.

priceSource

advertised = read off the page; estimated = computed by us (not produced today).

freshness

price and sold-out are re-pulled on a tiered cadence; every row carries lastChecked so you always know how current it is.

3 days or less out

rechecked daily.

4 to 14 days out

rechecked every 3 days.

further out

rechecked weekly.

lastChecked

UTC timestamp of the most recent recheck on that row.

errors

standard HTTP codes. the body is JSON with a detail string.

200

ok. events may be an empty array when nothing matches.

401

missing or invalid X-API-Key.

429

rate limit. back off and retry. the ceiling is generous, well above normal polling.

404

the API is turned off (maintenance). rare, and announced.

access

$2,000 / month per city. one key, every query, all the data for that city.

keys are issued by us, not self-serve yet. request one from the keys page and we send credentials and a stripe invoice. existing customers mint and rotate their own keys on the keys page.

howfar api