Verkaufsoffener Sonntag APIverkaufsoffener-sonntag.com ↗
Query shopping Sundays (verkaufsoffene Sonntage) in Germany by date and state. Get venue names, opening hours, postal codes, and city data via 2 endpoints.
What is the Verkaufsoffener Sonntag API?
The verkaufsoffener-sonntag.com API provides structured access to German shopping Sunday listings through 2 endpoints. Use list_sunday_openings to retrieve all towns holding a verkaufsoffener Sonntag on a given date or within a specific Bundesland, and get_sunday_opening to fetch venue-level details — including opening and closing times — for any individual listing identified by its event_id.
curl -X GET 'https://api.parse.bot/scraper/196d8e01-216c-4fdb-8783-1f9a084fbda9/list_sunday_openings?state=bayern' \ -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 verkaufsoffener-sonntag-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: find shopping Sundays in Bavaria and inspect venue details."""
from parse_apis.verkaufsoffener_sonntag_com_api import (
VerkaufsoffenerSonntag,
State,
OpeningNotFound,
)
client = VerkaufsoffenerSonntag()
# List upcoming shopping Sundays in Bavaria, capped at 5 results.
for summary in client.opening_summaries.list(state=State.BAYERN, limit=5):
print(summary.date, summary.city, summary.postal_code or "n/a")
# Drill into the first result's full details via the summary→detail link.
first = client.opening_summaries.list(state=State.BAYERN, limit=1).first()
if first is not None:
detail = first.details()
print(detail.title, detail.date)
for venue in detail.openings:
print(f" {venue.venue}: {venue.opens}–{venue.closes}")
# Point lookup by a known event_id, with typed error handling.
try:
opening = client.openings.get(event_id=first.event_id) if first else None
if opening is not None:
print(opening.city, opening.state, opening.url)
except OpeningNotFound:
print("Event not found")
print("exercised: opening_summaries.list / openings.get / details / venues")
Lists towns with a shopping Sunday (verkaufsoffener Sonntag) in Germany. At least one of date or state must be given. With a date, all towns listed for that day across Germany are returned (optionally narrowed to one state); with only a state, every upcoming listed date for that state is returned (typically several hundred rows, one round trip). One row per town-and-date; each row carries an event_id usable with get_sunday_opening. A date the site has no listing page for (e.g. a weekday) returns an empty items list with date_listed=false, which is a valid empty result. postal_code may be null for a few large-city entries. Single request, no pagination.
| Param | Type | Description |
|---|---|---|
| date | string | Calendar day in ISO form YYYY-MM-DD. Shopping Sundays are usually Sundays or public holidays; other days return an empty list. Omit to list all upcoming dates for the given state. |
| state | string | German federal state (Bundesland) slug. With a date it filters that day's list; without a date it selects the state's full upcoming schedule. |
{
"type": "object",
"fields": {
"date": "echo of the requested ISO date, or null when only a state was given",
"items": "array of town rows: event_id (slug for get_sunday_opening), date (ISO), state (display name), postal_code (string or null), city, url",
"state": "display name of the requested state, or null when only a date was given",
"total": "integer count of items",
"date_listed": "boolean: false when the site has no listing page for the requested date (items is then empty)"
},
"sample": {
"data": {
"date": "2026-09-13",
"items": [
{
"url": "https://www.verkaufsoffener-sonntag.com/event/verkaufsoffener-sonntag-in-essen-am-13-september-2026/",
"city": "Essen",
"date": "2026-09-13",
"state": "Nordrhein-Westfalen",
"event_id": "verkaufsoffener-sonntag-in-essen-am-13-september-2026",
"postal_code": null
},
{
"url": "https://www.verkaufsoffener-sonntag.com/event/verkaufsoffener-sonntag-in-minden-am-13-september-2026/",
"city": "Minden",
"date": "2026-09-13",
"state": "Nordrhein-Westfalen",
"event_id": "verkaufsoffener-sonntag-in-minden-am-13-september-2026",
"postal_code": "32423"
}
],
"state": "Nordrhein-Westfalen",
"total": 34,
"date_listed": true
},
"status": "success"
}
}About the Verkaufsoffener Sonntag API
Listing Shopping Sundays by Date or State
list_sunday_openings accepts a date (ISO format YYYY-MM-DD), a state slug, or both. Providing only a date returns every town across Germany listed for that day; adding a state slug narrows results to that Bundesland. Providing only a state returns all upcoming shopping Sundays listed for that state. The response includes a total count and an items array where each row carries event_id, date, state, city, postal_code (string or null), and additional fields. A date_listed boolean signals whether the source has a listing page for the requested date at all — when false, items is empty.
Venue and Opening-Hour Details
get_sunday_opening takes an event_id sourced from list_sunday_openings.items[*].event_id and returns the full detail record for that town's shopping Sunday. The openings array is the core payload: each entry has a venue name (the occasion or retailer), plus opens and closes times in HH:MM format. The response also echoes city, postal_code, date, state, title, and a url pointing to the source listing page.
Coverage and Data Shape
Coverage is limited to listings published on verkaufsoffener-sonntag.com, which aggregates municipally announced shopping Sundays in Germany. Not every town in every state is listed; only events the source has indexed appear in results. Postal codes may be null for some entries. The state field in list_sunday_openings returns a display name, not the slug used as input — the slug is the value passed to the state parameter.
The Verkaufsoffener Sonntag API is a managed, monitored endpoint for verkaufsoffener-sonntag.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when verkaufsoffener-sonntag.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 verkaufsoffener-sonntag.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 weekend shopping planner that shows open stores in a user's German city on a given Sunday
- Aggregate upcoming shopping Sundays across all Bundesländer for a retail foot-traffic analysis dashboard
- Send push notifications to app users when a verkaufsoffener Sonntag is announced in their postal code area
- Populate a calendar widget with shopping Sunday dates filtered to a specific federal state
- Cross-reference venue opening hours from
openingswith store location data for route planning - Track how many towns hold shopping Sundays on the same date using the
totalfield fromlist_sunday_openings
| 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 verkaufsoffener-sonntag.com offer an official developer API?+
What does `date_listed` mean in the `list_sunday_openings` response?+
date_listed is a boolean that indicates whether the source has a listing page for the requested date. When it is false, no shopping Sunday page exists for that day and the items array will be empty. This lets you distinguish between a date with zero events and a date the source has simply not indexed.Can I retrieve opening hours for all venues in a state without specifying individual event IDs?+
list_sunday_openings returns town-level rows with event_id values, and get_sunday_opening must be called per event_id to get openings with venue-level HH:MM hours. Bulk venue-hour retrieval across a full state would require iterating over the items list. You can fork this API on Parse and revise it to add a bulk-detail endpoint if that pattern fits your use case.Does the API cover weekday or Saturday retail openings in Germany?+
Are postal codes always present in the responses?+
postal_code field is a string when the source provides one, but it may be null for some city entries in both list_sunday_openings items and get_sunday_opening responses. Applications that depend on postal codes for geo-filtering should handle null values explicitly.