bissl-at Venues API

openapi: 3.2.0
info:
  description: 'Dishes, prices and lunch menus of restaurants, cafés and bars in Austria, read from each place''s own website. Free to use, but not to pass on, all or in large part, as your own collection of places'' menus and prices (a site, app or dataset); systematic or large-scale fetching, commercial market analysis, historical data and training AI models need a licence; text and data mining is reserved (§ 42h of the Austrian Copyright Act); photos and reviews are not included. Name bissl as the source and link to the place''s bissl page (`url`) wherever you show its data. Terms: https://bissl.at/en/api'
  title: bissl Venues API
  version: '1'
servers:
- url: https://api.bissl.at
tags:
- name: Venues
paths:
  /v1/venues:
    get:
      operationId: listVenues
      parameters:
      - description: 'Keep to a map area: "west,south,east,north" in degrees - a town, a district, the streets around a place. Everywhere when left out.'
        in: query
        name: bbox
        schema:
          type: string
      - description: 'Only at places of this cuisine, as OpenStreetMap names it: "italian", "vietnamese".'
        in: query
        name: cuisine
        schema:
          type: string
      - description: Only places whose menu with prices bissl read.
        in: query
        name: has_menu
        schema:
          type: boolean
      - description: 'Its kind as OpenStreetMap tags it: restaurant, fast_food, cafe, bar, pub, biergarten, ice_cream, food_court, bakery or pastry.'
        in: query
        name: kind
        schema:
          type: string
      - description: 'The language of dish names, descriptions and section titles: de, the menus'' own, or en, as bissl translated them.'
        in: query
        name: lang
        schema:
          enum:
          - de
          - en
          type: string
      - description: The latitude of a point - the user's, or one they name - to measure distances from and sort nearest first; with `lon`.
        in: query
        name: lat
        schema:
          format: double
          type: number
      - description: 'Places to answer with: 1 to 30, 10 when left out.'
        in: query
        name: limit
        schema:
          format: int64
          type: integer
      - description: The longitude of that point; with `lat`.
        in: query
        name: lon
        schema:
          format: double
          type: number
      - description: Only places serving a lunch menu today.
        in: query
        name: lunch_today
        schema:
          type: boolean
      - description: 'Places to skip, for the next ones: 0 when left out.'
        in: query
        name: offset
        schema:
          format: int64
          type: integer
      - description: Only places open right now.
        in: query
        name: open_now
        schema:
          type: boolean
      - description: 'Words to search for among the places: part of a name - "figlm" finds Figlmüller.'
        in: query
        name: q
        schema:
          type: string
      - description: The order of the places.
        in: query
        name: sort
        schema:
          anyOf:
          - oneOf:
            - enum:
              - name
              type: string
            - description: 'The most useful places first: with a menu, prices, photos, open now.'
              enum:
              - recommended
              type: string
            - description: The cheapest price level first.
              enum:
              - price
              type: string
            - description: Nearest to `lat`, `lon` first - the order whenever they are given, unless another.
              enum:
              - distance
              type: string
          - enum:
            - null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VenuesAnswer'
          description: The answer
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: A parameter the API can't read, and why
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: No such place
        '429':
          description: 'Too many requests from this address: wait for Retry-After'
      summary: Places to eat and drink, filtered and sorted
      tags:
      - Venues
  /v1/venues/{slug}:
    get:
      operationId: getVenue
      parameters:
      - description: The place's slug, from a search's or a list's answer.
        in: path
        name: slug
        required: true
        schema:
          type: string
      - description: 'The language of dish names, descriptions and section titles: de, the menus'' own, or en, as bissl translated them.'
        in: query
        name: lang
        schema:
          enum:
          - de
          - en
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VenueAnswer'
          description: The answer
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: A parameter the API can't read, and why
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: No such place
        '429':
          description: 'Too many requests from this address: wait for Retry-After'
      summary: A place, its opening hours and every menu bissl read
      tags:
      - Venues
components:
  schemas:
    VenueAnswer:
      properties:
        attribution:
          type: string
        checked_on:
          description: 'The day its menus were last read from its website, or the day a visitor sent the

            photos they were read from.'
          format: date
          type:
          - string
          - 'null'
        email:
          description: 'Its email address, as its own website gives it: "info@figlmueller.at".'
          type:
          - string
          - 'null'
        menu_source:
          anyOf:
          - $ref: '#/components/schemas/MenuSource'
          - enum:
            - null
          description: 'Where its menus were read: "website", its own website, or "visitor_photo", photos of

            its printed menu a visitor sent and bissl checked. Null when it has no menu.'
        menus:
          description: 'Its regular food and drinks, and its lunch of this week; none when bissl has no

            menu of it.'
          items:
            $ref: '#/components/schemas/Menu'
          type: array
        opening_hours:
          description: 'Its opening hours in OpenStreetMap''s syntax: "Mo-Fr 11:00-22:00; Sa 12:00-22:00".'
          type:
          - string
          - 'null'
        phone:
          description: 'Its phone number, Austrian, as dialled from abroad without spaces: "+4315126177".'
          type:
          - string
          - 'null'
        place:
          $ref: '#/components/schemas/Place'
        website:
          description: Its own website.
          type:
          - string
          - 'null'
      required:
      - place
      - phone
      - email
      - website
      - opening_hours
      - checked_on
      - menu_source
      - menus
      - attribution
      type: object
    VenuesAnswer:
      properties:
        attribution:
          type: string
        cuisine:
          description: The cuisine kept to, when one was asked for.
          type:
          - string
          - 'null'
        note:
          description: Why there is nothing, when there is a reason to say.
          type:
          - string
          - 'null'
        places:
          items:
            $ref: '#/components/schemas/PlaceListing'
          type: array
        total_places:
          description: Places matching, of which `places` holds `limit` from `offset` on.
          format: int64
          type: integer
      required:
      - cuisine
      - total_places
      - places
      - note
      - attribution
      type: object
    ApiDiet:
      description: A diet as a menu marks a dish, or the dish's name says it.
      oneOf:
      - enum:
        - vegan
        type: string
      - description: Vegetarian, vegan dishes included.
        enum:
        - vegetarian
        type: string
    Place:
      description: A place to eat or drink, the same in every answer.
      properties:
        address:
          description: Street, house number, postcode and town; null when bissl has none.
          type:
          - string
          - 'null'
        area:
          description: 'Its district or town, to say where it is: "7. Neubau", "Mödling"; null outside every

            town bissl knows. No filter takes it.'
          type:
          - string
          - 'null'
        cuisines:
          description: 'Its cuisines as OpenStreetMap names them: austrian, italian, pizza, vietnamese...'
          items:
            type: string
          type: array
        distance_m:
          description: Metres from the point asked about (`lat`, `lon`), when one was given.
          format: int64
          type:
          - integer
          - 'null'
        kind:
          description: 'Its kind as OpenStreetMap tags it: restaurant, fast_food, cafe, bar, pub,

            biergarten, ice_cream, food_court, bakery or pastry.'
          type: string
        lat:
          format: double
          type: number
        lon:
          format: double
          type: number
        name:
          type: string
        open_now:
          description: Open right now by its opening hours (Vienna's time); null when bissl can't read them.
          type:
          - boolean
          - 'null'
        part_of:
          description: 'The larger place it is part of, as its own website names it - the hotel, castle or

            club its restaurant or bar is in: "Das Schloss an der Eisenstrasse". Null for none.'
          type:
          - string
          - 'null'
        price_level:
          description: '"€" to "€€€€" from its menu''s prices, against places of its kind - a restaurant''s

            mains, a café''s coffee and cake, a bar''s cocktails; null while bissl doesn''t know.'
          type:
          - string
          - 'null'
        slug:
          description: 'bissl''s name for the place: what `/v1/venues/{slug}` and `get_venue` take.'
          type: string
        url:
          description: 'Its page on bissl, with every menu: link to it.'
          type: string
      required:
      - slug
      - name
      - part_of
      - kind
      - cuisines
      - address
      - area
      - lat
      - lon
      - open_now
      - distance_m
      - price_level
      - url
      type: object
    Menu:
      properties:
        kind:
          $ref: '#/components/schemas/MenuKind'
        sections:
          items:
            $ref: '#/components/schemas/MenuSection'
          type: array
        served:
          description: 'When a lunch is served, as its page says: "Mo–Fr · 11:30–14:30". Lunch only.'
          type:
          - string
          - 'null'
        title:
          description: '"Speisen", "Getränke", "Mittagsmenü" - or in English.'
          type: string
        valid_from:
          description: The first and last day a lunch menu is for, when it says.
          format: date
          type:
          - string
          - 'null'
        valid_to:
          format: date
          type:
          - string
          - 'null'
      required:
      - kind
      - title
      - valid_from
      - valid_to
      - served
      - sections
      type: object
    MenuKind:
      enum:
      - food
      - drinks
      - lunch
      type: string
    Dish:
      description: A dish or drink on a menu, the same in every answer.
      properties:
        allergens:
          description: 'The allergen letters its menu lists, by the Austrian codes (A gluten, B

            crustaceans, C egg, D fish, E peanuts, F soy, G milk, H nuts, L celery, M mustard,

            N sesame, O sulphites, P lupin, R molluscs); null when the menu lists none for it,

            which is no promise it has none.'
          type:
          - string
          - 'null'
        checked_on:
          description: The day its menu was last read from the venue's website.
          format: date
          type:
          - string
          - 'null'
        description:
          type: string
        diet:
          anyOf:
          - $ref: '#/components/schemas/ApiDiet'
          - enum:
            - null
          description: Vegan or vegetarian as the menu marks it or its name says; null when neither.
        id:
          description: bissl's id of the dish on its menu.
          format: int64
          type: integer
        name:
          type: string
        prices:
          description: One per size or variant; none when the menu gives no price.
          items:
            $ref: '#/components/schemas/Price'
          type: array
        served_on:
          description: The day a lunch dish is served on; null for what the place always serves.
          format: date
          type:
          - string
          - 'null'
        url:
          description: The venue's bissl page with this dish marked.
          type: string
      required:
      - id
      - name
      - description
      - prices
      - diet
      - allergens
      - served_on
      - checked_on
      - url
      type: object
    Price:
      description: 'A price of a dish: one per size or variant.'
      properties:
        note:
          description: 'What it is for, when the menu says: a size or a variant ("0,5 l", "klein").'
          type: string
        price:
          description: 'As the venue page writes it: "12,90 €".'
          type:
          - string
          - 'null'
        price_cents:
          description: In euro cents; null when the menu names a size without a price.
          format: int64
          type:
          - integer
          - 'null'
      required:
      - price_cents
      - price
      - note
      type: object
    MenuSource:
      description: Where a place's menus were read.
      oneOf:
      - description: Its own website.
        enum:
        - website
        type: string
      - description: Photos of its printed menu a visitor sent and bissl checked.
        enum:
        - visitor_photo
        type: string
    PlaceListing:
      description: A place in the list of places.
      properties:
        has_menu:
          description: bissl read a menu with prices from its website.
          type: boolean
        lunch_today:
          description: It serves a lunch menu today.
          type: boolean
        place:
          $ref: '#/components/schemas/Place'
      required:
      - place
      - has_menu
      - lunch_today
      type: object
    MenuSection:
      description: 'A part of a menu, as the venue page''s tab: "Vorspeisen", a lunch day''s "Mo 5.10.".'
      properties:
        dishes:
          items:
            $ref: '#/components/schemas/Dish'
          type: array
        title:
          description: Null for a menu of one section.
          type:
          - string
          - 'null'
      required:
      - title
      - dishes
      type: object