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`, `geojson`, `parquet`, or `xlsx`.

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

WIC authorization currently has a verified source in 20 states (AL, AZ, CA, CO, CT, FL, GA, IL, IN, LA, MI, MN, MS, NC, NJ, NY, PA, TX, UT, and the Wichita, KS metro area only) plus Washington DC. Every other state returns null, meaning not yet evaluated, never interpreted as "not authorized."
Phone number and pharmacy flag are unavailable for banners sourced from the USDA SNAP retailer dataset (most convenience, discount, and many regional grocery banners); that source doesn't carry either field. Banners sourced directly from a retailer's own store locator do include them.
Crime index is live, sourced from the FBI Crime Data Explorer and matched to each store's nearest reporting law enforcement agency. Coverage is around 79% of active stores as of 2026-08-24 and growing. A store without a nearby reporting agency, or whose agency hasn't published a usable rate, returns null rather than a guessed value.
Food desert, Opportunity Zone, daytime population, and diabetes/obesity prevalence were added 2026-08-21 and are being backfilled across the existing store catalog. Coverage grows as that backfill and the weekly refresh process more of the catalog. A store you've already purchased that showsnull for one of these today may show a real value on a later export once its area has been processed, with no re-purchase needed.
Rate limits: there is no hard rate limit enforced today. For high-volume or bulk programmatic use (e.g. a full-category subscription polled frequently), reach out so we can make sure your usage pattern is a good fit.