Valpak APIvalpak.com ↗
Query Valpak's local coupon listings by US ZIP code. Returns business name, offer title, distance, logo, and coupon URL for nearby deals.
What is the Valpak API?
The Valpak API exposes one endpoint — search_local_coupons — that returns an array of coupon objects for brick-and-mortar businesses near any US ZIP code, with up to five response fields per coupon including business_name, title, distance, logo_url, and coupon_url. Results span restaurants, automotive shops, personal care services, home services, and retail stores. An optional category parameter narrows results to a specific business type, making it straightforward to pull targeted local offer data.
curl -X GET 'https://api.parse.bot/scraper/16e1c43c-41aa-4a07-b0c9-445d367cb5a5/search_local_coupons?category=restaurants&zip_code=90210' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace valpak-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Valpak SDK — bounded, re-runnable; every call capped."""
from parse_apis.valpak_com_api import Valpak, Category, ZipCodeNotFound
client = Valpak()
# Search local coupons near a zip code, limited to 3 results.
for coupon in client.coupon_search_results.search(zip_code="90210", limit=3):
print(coupon.title, coupon.business_name, coupon.distance)
# Filter by category — restaurants only.
for coupon in client.coupon_search_results.search(
zip_code="10001", category=Category.RESTAURANTS, limit=3
):
print(coupon.title, coupon.business_name)
# Handle a bad zip code gracefully.
try:
result = client.coupon_search_results.search(zip_code="00000", limit=1).first()
except ZipCodeNotFound as e:
print(f"invalid zip: {e.zip_code}")
print("exercised: coupon_search_results.search")
Search for local coupons and deals near a US zip code. Returns brick-and-mortar business offers including restaurants, automotive services, personal care, home services, and more. Results are ordered by distance from the zip code center. An optional category narrows results to one business type. Each coupon includes the offer title, business name, distance, and a link to the full coupon details.
| Param | Type | Description |
|---|---|---|
| category | string | Filter coupons by business category. Omitted returns all categories. |
| zip_coderequired | string | 5-digit US ZIP code (e.g. 90210). Leading zeros preserved. |
{
"type": "object",
"fields": {
"total": "Number of coupons returned",
"coupons": "Array of coupon objects with title, business_name, distance, logo_url, and coupon_url",
"category": "The category filter applied, or null if none",
"location": "Resolved city and state name (e.g. 'Beverly Hills, CA')",
"zip_code": "The queried zip code"
},
"sample": {
"data": {
"total": 25,
"coupons": [
{
"title": "buy an original combo and get an original burger free",
"distance": "1 Mile Away",
"logo_url": "https://cdn1.valpak.com/img/print/FatburgerSince1952Logo_4CTI.tif",
"coupon_url": "https://www.valpak.com/local/beverly-hills-ca/fatburger-220735?store=319660",
"business_name": "fatburger"
},
{
"title": "$5 off any $25 purchase",
"distance": "6.6 Miles Away",
"logo_url": "https://cdn1.valpak.com/img/print/SharkysShermanOaksLOGO.PNG",
"coupon_url": "https://www.valpak.com/local/beverly-hills-ca/sharkys-woodfired-mexican-grill-marina-del-rey-158055?store=238389",
"business_name": "sharky's woodfired mexican grill"
}
],
"category": "restaurants",
"location": "Beverly Hills, CA",
"zip_code": "90210"
},
"status": "success"
}
}About the Valpak API
What the API Returns
The search_local_coupons endpoint accepts a required zip_code (5-digit US ZIP, leading zeros preserved) and an optional category string. The response envelope includes total (count of matched coupons), the queried zip_code, a resolved location string such as Beverly Hills, CA, the category filter applied or null if none, and the coupons array itself.
Coupon Object Fields
Each item in the coupons array carries: title (the offer text as listed by the business), business_name, distance (miles from the ZIP code centroid, enabling proximity-sorted results), logo_url (a direct image link to the business logo), and coupon_url (a link to the full offer detail page on Valpak). Results are already ordered by distance ascending, so the closest businesses appear first.
Filtering by Category
Omitting the category parameter returns all available local offers across every business type near the ZIP. Providing a category value — such as a restaurant type, automotive service, or home improvement category — restricts results to matching listings. The category field in the response echoes back whichever filter was applied, or null for unfiltered queries, which is useful for caching or logging.
Coverage and Scope
Coverage is limited to US ZIP codes only. Valpak's network concentrates on businesses that run direct-mail and digital coupon campaigns, so not every local business will appear — the dataset reflects active advertisers rather than a general business directory. Results reflect the current promotional cycle, so the offer set for a given ZIP will change as businesses update their campaigns.
The Valpak API is a managed, monitored endpoint for valpak.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when valpak.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official valpak.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a hyperlocal deal-finder app that surfaces restaurant and retail coupons sorted by distance for a given ZIP code
- Aggregate
business_nameandcoupon_urldata to populate a savings widget on a neighborhood or community website - Monitor which business categories are running active promotions in a specific ZIP to inform local advertising strategy
- Enrich a local business directory by matching
logo_urland offer titles to existing business records - Track
totalcoupon counts across multiple ZIP codes over time to measure promotional density by region - Filter by automotive or home services category to build a targeted comparison page for local service providers
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Valpak have an official developer API?+
What does the `distance` field represent and how are results ordered?+
distance field is the number of miles between the queried ZIP code's geographic center and the business location. The coupons array is returned pre-sorted in ascending order by distance, so index 0 is always the closest matching business.Does the API return coupon expiration dates or discount amounts?+
title, business_name, distance, logo_url, and coupon_url, but structured fields for expiration dates or specific discount values are not part of the response. You can fork this API on Parse and revise it to add an endpoint that fetches the individual coupon detail page via coupon_url to extract those fields.Is the API limited to US locations?+
zip_code parameter accepts only 5-digit US ZIP codes, and all returned location values resolve to US city and state names. Non-US postal codes are not supported. You can fork this API on Parse and revise it to point at a different regional coupon source if you need non-US coverage.Does the API return pagination or only a single page of results?+
search_local_coupons endpoint returns all available coupons for the ZIP and category in one response, with the count reflected in the total field. There is no pagination cursor or page parameter in the current spec. You can fork this API on Parse and revise it to add offset-based pagination if the result set for dense ZIP codes needs to be chunked.