API Documentation

Programmatic access to every banner you've purchased or subscribed to. All endpoints return the same live data as the dashboard export - there is no separate, staler copy.

Authentication

Generate a key from your dashboard and send it as the x-api-key header on every request. One key works across every banner and category you have access to - keys aren't scoped to a single banner.

curl -H "x-api-key: rtl_..." \
  "https://synapse.afferentsignal.com/api/v1/banner-data?banner_id=<uuid>&format=json"

Endpoints

GET/api/v1/banner-data

Returns the full current store list for one banner, gated to your purchased/subscribed tier and states. Fields above your tier are returned as null, never omitted, so the response shape is stable regardless of tier.

Param	Required	Description
banner_id	Yes	UUID, from the catalog page or /catalog listing.
format	No, default json	`csv`, `json`, or `geojson`.

GET/api/v1/banner-data/delta

Returns only what changed since a given timestamp - stores opened, closed, or updated - instead of the full dataset. This is the intended way to stay continuously current: poll on whatever cadence you need and pass the last timestamp you saw back in as since, rather than re-downloading the full export every time.

Param	Required	Description
banner_id	Yes	UUID.
since	Yes	ISO 8601 timestamp. Returns changes strictly after this time.

Capped at 5,000 changes per call (truncated: true in the response if hit) - for a first sync, call the main export endpoint instead, then switch to delta polling from that point forward.

GET/api/v1/category-data

Requires either a one-time category purchase or an active category subscription. Streams every banner in that category as one file, tagged with banner_id/banner_name per row - the bulk path for a "buy the whole category" integration instead of calling /banner-data once per banner. A one-time purchase covers only the banners that existed at purchase time; a subscription also covers banners added to the category later.

Param	Required	Description
category	Yes	One of the categories listed below.
format	No, default csv	`csv` or `jsonl` (newline-delimited JSON - a single category can span tens of thousands of stores, so this streams rather than building one large JSON array in memory).

Data freshness

The full store universe is re-verified on a weekly crawl cadence; last_scraped_at on each store tells you exactly when. A subscription (as opposed to a one-time purchase) doesn't change how often the underlying data is refreshed - it changes how long your access stays current: a one-time purchase is a snapshot of the data at checkout, while a subscription keeps returning live, current results for as long as it stays active, with no need to re-purchase.

Fields and tier gating

Every field is present in every response; fields above your purchased/subscribed tier come back as null rather than being omitted.

Field	Tier	Description
store_id	Baseline	Internal unique identifier (UUID).
store_number	Baseline	The retailer's own store number where available. Not populated for USDA SNAP-sourced banners (no equivalent field in that source) - see Coverage notes below.
address, city, state, zip_code	Baseline	Street address, parsed into components.
lat, long	Baseline	Decimal degrees, WGS84.
phone	Baseline	Not populated for USDA SNAP-sourced banners (no phone field in that source).
pharmacy_flag	Baseline	Whether the store has an in-store pharmacy. Not populated for SNAP-sourced banners.
status	Baseline	ACTIVE or CLOSED, as of the last weekly crawl.
last_scraped_at	Baseline	Timestamp this store record was last verified against its source.
total_population	Mid-tier	Census tract population (ACS 5-year estimate).
median_household_income	Mid-tier	Census tract median household income, in USD (ACS 5-year estimate).
affluence_index	Mid-tier	A composite 0-100 score derived from tract income and population density.
ethnicity_breakdown_json	Mid-tier	Census tract ethnicity breakdown by percentage, as a JSON object.
daytime_population	Mid-tier	Workplace/daytime population - jobs located in this store's census block (Census LODES), distinct from total_population which is residential.
snap_authorized	Premium	Whether the store is USDA SNAP-authorized (true/false).
wic_authorized	Premium	Whether the store is a verified WIC vendor. true/false only for the states with a confirmed source (see Coverage notes) - null everywhere else, meaning "not evaluated," never treated as a negative result.
ev_charger_present, ev_charger_count	Premium	Presence and count of EV chargers within the property, sourced from the DOE Alternative Fuels Data Center.
ev_networks, ev_dc_fast_count	Premium	Distinct charging network names (e.g. Tesla, ChargePoint, EVgo) and count of DC fast chargers among the nearby stations, from the same NREL AFDC data as ev_charger_count.
primary_road_aadt	Premium	Annual Average Daily Traffic on the nearest primary road (FHWA National Highway System), vehicles/day.
competitive_density_3mi	Premium	Count of same-channel competitor stores within a 3-mile radius.
food_desert	Premium	USDA ERS Food Access Research Atlas low-income/low-access tract designation for this store's location.
opportunity_zone	Premium	Whether this store sits in a federally-designated Qualified Opportunity Zone (Treasury/CDFI Fund).
crime_index	Premium	Violent + property crime rate per 1,000 population, from the FBI Crime Data Explorer.
diabetes_prevalence_pct, obesity_prevalence_pct	Premium	CDC PLACES modeled prevalence among adults in this store's ZIP Code Tabulation Area.
recreation_site_count, nearest_recreation_distance_mi	Premium	Count of national parks/forests/BLM-BOR-Corps recreation areas and federal campgrounds within 25 miles, and distance in miles to the single nearest one - a seasonal foot-traffic signal, from Recreation.gov's Recreation Information Database (RIDB).

Coverage notes