Skip to content

Instantly share code, notes, and snippets.

@OzTamir

OzTamir/wolt_api.md

Created December 20, 2025 09:07
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save OzTamir/7ed2b49b8628d88c086d65b0d1730c36 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save OzTamir/7ed2b49b8628d88c086d65b0d1730c36 to your computer and use it in GitHub Desktop.
Download ZIP
Wolt API Documentation
Raw
wolt_api.md

Wolt API

This document describes the Wolt web API endpoints and response models used in this codebase.

Base URLs

  • Consumer API: https://consumer-api.wolt.com/v1/
  • Restaurant API: https://restaurant-api.wolt.com/
  • Auth API: https://authentication.wolt.com/v1/wauth2/access_token

Common Inputs

Most calls require latitude and longitude (string values in PyWolt):

  • lat: latitude
  • lon: longitude

Endpoints

List Available Venues

GET https://consumer-api.wolt.com/v1/pages/restaurants

Query parameters:

  • lat (string, required)
  • lon (string, required)

Response shape (used):

  • sections (array)
    • sections[1].items -> list of venue entries
    • if sections[1] missing, PyWolt raises ValueError(sections[0]["title"])

Mapping: each item is parsed into VenueData.

Verified curl:

curl "https://consumer-api.wolt.com/v1/pages/restaurants?lat=32.081171&lon=34.780663"

Example response (trimmed, sections[1].items[0]):

{
  "title": "Doron's Jachnun | Tel Aviv",
  "venue": {
    "id": "5fa3c2044aed93975b5034e8",
    "name": "Doron's Jachnun | Tel Aviv",
    "slug": "dorons-jachnun-tel-aviv",
    "city": "",
    "online": true,
    "estimate": 25,
    "price_range": 1
  },
  "image": {
    "url": "https://imageproxy.wolt.com/assets/673207a063ae2357e7f7bae9"
  }
}

Venue Menu

GET https://restaurant-api.wolt.com/v4/venues/slug/{venue_slug}/menu/data

Path parameters:

  • venue_slug (string, required)

Query parameters:

  • unit_prices (bool, default true)
  • show_weighted_items (bool, default true)
  • show_subcategories (bool, default true)

Response shape (used):

  • items -> list of menu items

Mapping: each item is parsed into MenuItem.

Verified curl (example venue slug):

curl "https://restaurant-api.wolt.com/v4/venues/slug/dorons-jachnun-tel-aviv/menu/data?unit_prices=true&show_weighted_items=true&show_subcategories=true"

Example response (illustrative, items[0]):

{
  "id": "item-123",
  "name": "Jachnun Plate",
  "description": "Slow-cooked dough with egg and tomato",
  "baseprice": 4500,
  "enabled": true,
  "category": "Main"
}

Note: in this environment the verified curl returned HTTP 200 with an empty body. The example above reflects the fields used by MenuItem.

Search Venues

POST https://restaurant-api.wolt.com/v1/pages/search

JSON body:

  • q (string, required)
  • target = "venues"
  • lat (string, required)
  • lon (string, required)

Response shape (used):

  • sections[0]
    • items -> list of venues
    • if items missing, PyWolt raises ValueError(sections[0]["title"])

Mapping: each item is parsed into VenueData.

Verified curl:

curl -X POST "https://restaurant-api.wolt.com/v1/pages/search" \
  -H "Content-Type: application/json" \
  -d '{"q":"pizza","target":"venues","lat":"32.081171","lon":"34.780663"}'

Example response (trimmed, sections[0].items[0]):

{
  "venue": {
    "id": "6391d920eff86a03af7da1dd",
    "name": "NonoMimi | Givataim",
    "slug": "nono-givaataim"
  },
  "title": "NonoMimi | Givataim"
}

Search Items

POST https://restaurant-api.wolt.com/v1/pages/search

JSON body:

  • q (string, required)
  • target = "items"
  • lat (string, required)
  • lon (string, required)

Response shape (used):

  • sections[0].items[].menu_item -> list of menu items
    • if items missing, PyWolt raises ValueError(sections[0]["title"])

Mapping: each menu_item is parsed into ItemSearchResult.

Verified curl:

curl -X POST "https://restaurant-api.wolt.com/v1/pages/search" \
  -H "Content-Type: application/json" \
  -d '{"q":"pizza","target":"items","lat":"32.081171","lon":"34.780663"}'

Example response (trimmed, sections[0].items[0].menu_item):

{
  "id": "5fa4014fce8409f03cf7f858",
  "name": "Tabun Oven Pizza",
  "price": 2700,
  "currency": "ILS",
  "venue_name": "Tabun Ben Yehuda"
}

List Cities

GET https://restaurant-api.wolt.com/v1/cities

Response shape (used):

  • results -> list of cities

Mapping: each item is parsed into City.

Verified curl:

curl "https://restaurant-api.wolt.com/v1/cities"

Example response (trimmed, results[0]):

{
  "id": "6567403295041dcfeb69bc23",
  "name": "Tirana",
  "slug": "tirana",
  "timezone": "Europe/Tirane",
  "country_code_alpha2": "AL"
}

Refresh Access Token

POST https://authentication.wolt.com/v1/wauth2/access_token

Form data:

  • refresh_token (string, required)
  • grant_type = "refresh_token"

Response shape (used):

  • access_token
  • refresh_token

Mapping: stored on the Wolt instance.

Example omitted here because it requires a valid refresh_token.

Data Models (Pydantic)

The following models are used to parse responses. Fields are listed with their types as defined in pywolt/data_structures.py.

SortingSortables

  • id: str
  • value: int

FilteringFilters

  • id: str
  • values: List[str]

VenueRating

  • rating: int
  • score: float

Image

  • blurhash: Optional[str]
  • url: str

Link

  • selected_delivery_method: str
  • target: str
  • target_sort: str
  • target_title: str
  • title: str
  • type: str
  • venue_mainimage_blurhash: str

OverlayV2

  • icon: Optional[str]
  • primary_text: str
  • secondary_text: Optional[str]
  • telemetry_status: str
  • variant: str

VenueData

High-level wrapper for venue list/search responses.

  • filtering: Dict[str, List[FilteringFilters]]
  • image: Image
  • link: Link
  • sorting: Dict
  • telemetry_venue_badges: List[str]
  • template: str
  • title: str
  • track_id: str
  • venue: Venue
  • overlay: Optional[str]
  • overlay_v2: Optional[OverlayV2]

Venue

Represents a venue (restaurant, grocery shop, etc).

  • address: str
  • badges: List[dict]
  • badges_v2: List[str]
  • categories: List[str]
  • city: str
  • country: CountryAlpha3
  • currency: ISO4217
  • delivers: bool
  • delivery_price: Optional[Union[str, dict]]
  • delivery_price_highlight: bool
  • delivery_price_int: Optional[int]
  • estimate: int
  • estimate_range: str
  • franchise: str
  • icon: Optional[str]
  • id: str
  • location: Coordinates
  • name: str
  • online: bool
  • price_range: int
  • product_line: str
  • promotions: List[Dict[str, str]]
  • rating: Optional[VenueRating]
  • short_description: Optional[str]
  • show_wolt_plus: bool
  • slug: str
  • tags: List[str]

MenuItemOption

  • id: str
  • name: str
  • maximum_single_selections: int
  • maximum_total_selections: int
  • minimum_total_selections: int
  • parent: str
  • required_option_selections: list

MenuItem

Represents a menu item in a venue menu.

  • advertising_badge: Optional[str]
  • advertising_metadata: Optional[Dict[str, Any]]
  • alcohol_percentage: float
  • allowed_delivery_methods: List[str]
  • barcode_gtin: Optional[str]
  • baseprice: int
  • brand_id: Optional[str]
  • caffeine_content: Optional[dict]
  • category: str
  • checksum: str
  • deposit: Optional[float]
  • deposit_type: Optional[str]
  • description: str
  • dietary_preferences: List[str]
  • disabled_info: Optional[Dict[str, Any]]
  • enabled: bool
  • exclude_from_discounts: bool
  • exclude_from_discounts_min_basket: bool
  • fulfillment_lead_time: Optional[int]
  • has_extra_info: bool
  • id: str
  • images: List[Image]
  • is_cutlery: bool
  • lowest_historical_price: Optional[float]
  • mandatory_warnings: List[str]
  • max_quantity_per_purchase: Optional[int]
  • min_quantity_per_purchase: Optional[int]
  • name: str
  • no_contact_delivery_allowed: bool
  • options: List[MenuItemOption]
  • original_price: Optional[float]
  • quantity_left: Optional[int]
  • quantity_left_visible: bool
  • restrictions: Optional[List[Dict]]
  • return_policy: Optional[str]
  • sell_by_weight_config: Optional[Dict[str, Any]]
  • tags: List[dict]
  • times: List[Dict[str, Any]]
  • type: str
  • unformatted_unit_price: Optional[Dict]
  • unit_info: Optional[str]
  • unit_price: Optional[str]
  • validity: Optional[dict]
  • vat_percentage: float
  • wolt_plus_only: bool

Tag

  • background_color: Color
  • name: str
  • text_color: Color
  • variant: str

ItemSearchResult

Represents a menu item returned from an item search.

  • country: CountryAlpha3
  • currency: ISO4217
  • delivery_price: Optional[int]
  • delivery_price_highlight: bool
  • estimate_range: str
  • id: str
  • image: Optional[Image]
  • is_available: bool
  • name: str
  • price: int
  • price_type: str
  • show_wolt_plus: bool
  • tags: List[Union[str, dict]]
  • venue_id: str
  • venue_name: str
  • venue_rating: VenueRating

City

Represents a city supported by Wolt.

  • country_code_alpha2: CountryAlpha2
  • country_code_alpha3: CountryAlpha3
  • has_frontpage: bool
  • id: str
  • location: PointModel
  • name: str
  • slug: str
  • subareas: List[str]
  • timezone: str

Notes and Limitations

  • The codebase uses an async HTTP client for API requests; response models are Pydantic.
  • Error handling is minimal and mostly relies on missing sections or HTTP errors.
  • Basket operations are present but commented out in the codebase.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment