openapi: 3.1.0
info:
  title: OpenMenu Analytics Restaurants API
  version: 2.2.0
  description: The OpenMenu REST API returns structured restaurant and menu data built on the OpenMenu Format. Standard endpoints cover search, restaurant, location, deals, and ingredients, returning menu items with prices, locations, and dietary attributes. An Enhanced enterprise tier adds DishDNA machine-learning analysis, trends, heatmaps, and gap analysis. Authentication uses an API key passed as the `key` query parameter, and a sandbox mode (`s=sample` or `id=sample`) returns fixed sample JSON without consuming credits.
  contact:
    name: Kin Lane
    email: kin@apievangelist.com
  termsOfService: https://www.openmenu.com/tos-api.php
servers:
- url: https://www.openmenu.com/api/v2
  description: OpenMenu API v2 production server
security:
- ApiKeyAuth: []
tags:
- name: Restaurants
  description: Full restaurant profiles and geographic listings.
paths:
  /restaurant.php:
    get:
      operationId: getRestaurant
      summary: Get Restaurant Profile
      description: 'Return the full profile for one restaurant: contact and location, environment, hours, menus, and menu groups. Use `id=sample` for sandbox data.'
      tags:
      - Restaurants
      parameters:
      - $ref: '#/components/parameters/Key'
      - name: id
        in: query
        required: true
        description: Restaurant ID from a search or location response. Use `sample` for sandbox data.
        schema:
          type: string
      responses:
        '200':
          description: Full restaurant profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestaurantResponse'
        '400':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingInactive'
        '429':
          $ref: '#/components/responses/RateLimited'
  /location.php:
    get:
      operationId: listLocations
      summary: List Restaurants By Location
      description: List restaurants in a geographic area. Optionally filter by restaurant name using the `s` parameter. At least one of `postal_code` or `city` is required, along with `country`.
      tags:
      - Restaurants
      parameters:
      - $ref: '#/components/parameters/Key'
      - name: s
        in: query
        required: false
        description: Optional restaurant name filter.
        schema:
          type: string
      - name: offset
        in: query
        required: false
        description: Page index for paginated results (0-based). Maximum page index is 10 unless your key has paging limits removed.
        schema:
          type: integer
          minimum: 0
          maximum: 10
          default: 0
      - $ref: '#/components/parameters/PostalCode'
      - $ref: '#/components/parameters/City'
      - $ref: '#/components/parameters/State'
      - $ref: '#/components/parameters/Country'
      responses:
        '200':
          description: Restaurant listing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationResponse'
        '400':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingInactive'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    EnvironmentInfo:
      type: object
      properties:
        cuisine_type_primary:
          type: string
        cuisine_type_secondary:
          type: string
        smoking_allowed:
          type: boolean
        takeout_available:
          type: boolean
        seating_qty:
          type: integer
        max_group_size:
          type: integer
        pets_allowed:
          type: boolean
        wheelchair_accessible:
          type: boolean
        age_level_preference:
          type: string
        dress_code:
          type: string
        delivery_available:
          type: boolean
        delivery_radius:
          type: number
        delivery_fee:
          type: number
        catering_available:
          type: boolean
        reservations:
          type: string
        alcohol_type:
          type: string
        music_type:
          type: string
    Menu:
      type: object
      description: A single menu within a restaurant, per the OpenMenu Format.
      properties:
        menu_name:
          type: string
        menu_description:
          type: string
        menu_note:
          type: string
        currency_symbol:
          type: string
        language:
          type: string
        menu_duration_name:
          type: string
          enum:
          - breakfast
          - brunch
          - lunch
          - breakfast-lunch
          - dinner
          - lunch-dinner
          - late-night
          - all
        menu_duration_time_start:
          type: string
          description: Start time in hh:mm (ISO 8601, 24-hour).
        menu_duration_time_end:
          type: string
          description: End time in hh:mm (ISO 8601, 24-hour).
        menu_groups:
          type: array
          items:
            $ref: '#/components/schemas/MenuGroup'
    MenuItem:
      type: object
      description: A single menu item with prices, dietary flags, and allergens.
      properties:
        menu_item_name:
          type: string
        menu_item_description:
          type: string
        menu_item_price:
          type: string
        menu_item_calories:
          type: integer
        menu_item_heat_index:
          type: integer
        menu_item_allergy_information:
          type: object
          properties:
            menu_item_allergy_information_allergens:
              type: array
              items:
                type: string
                enum:
                - Egg
                - Fish
                - Dairy
                - Peanut
                - Shellfish
                - Soy
                - Tree Nut
                - Wheat
                - Gluten
        special:
          type: boolean
        vegetarian:
          type: boolean
        vegan:
          type: boolean
        kosher:
          type: boolean
        halal:
          type: boolean
        gluten_free:
          type: boolean
        menu_item_options:
          type: array
          items:
            type: object
        menu_item_sizes:
          type: array
          items:
            type: object
        menu_item_images:
          type: array
          items:
            type: string
    RestaurantSummary:
      type: object
      description: Compact restaurant record returned in search and location results.
      properties:
        id:
          type: string
        restaurant_name:
          type: string
        brief_description:
          type: string
        address_1:
          type: string
        address_2:
          type: string
        city_town:
          type: string
        state_province:
          type: string
        postal_code:
          type: string
        country:
          type: string
        longitude:
          type: number
        latitude:
          type: number
        cuisine_type_primary:
          type: string
        website_url:
          type: string
        mobile:
          type: string
        fDateUpdated:
          type: string
        social:
          type: object
          properties:
            facebook:
              type: string
            twitter:
              type: string
        totals:
          type: object
          properties:
            deals:
              type: integer
    OperatingDay:
      type: object
      properties:
        day_of_week:
          type: integer
        day:
          type: string
        day_short:
          type: string
        open_time:
          type: string
        close_time:
          type: string
        open_time_ampm:
          type: string
        close_time_ampm:
          type: string
    ApiEnvelope:
      type: object
      description: Standard `response.api` envelope returned with every call.
      properties:
        status:
          type: integer
          description: HTTP-style status code (e.g. 200).
        api_version:
          type: string
          description: API version, e.g. "2.2".
        format:
          type: string
          description: Response format, e.g. "json".
        api_key:
          type: boolean
          description: Whether a valid API key accompanied the request.
    RestaurantResponse:
      type: object
      properties:
        api:
          $ref: '#/components/schemas/ApiEnvelope'
        result:
          $ref: '#/components/schemas/Restaurant'
    MenuGroup:
      type: object
      properties:
        group_name:
          type: string
        group_note:
          type: string
        group_description:
          type: string
        menu_group_options:
          type: array
          items:
            type: object
        menu_items:
          type: array
          items:
            $ref: '#/components/schemas/MenuItem'
    LocationResponse:
      type: object
      properties:
        api:
          $ref: '#/components/schemas/ApiEnvelope'
        result:
          type: object
          properties:
            restaurants:
              type: array
              items:
                $ref: '#/components/schemas/RestaurantSummary'
    Restaurant:
      type: object
      description: Full restaurant profile built on the OpenMenu Format.
      properties:
        restaurant_info:
          $ref: '#/components/schemas/RestaurantInfo'
        environment_info:
          $ref: '#/components/schemas/EnvironmentInfo'
        operating_days:
          type: array
          items:
            $ref: '#/components/schemas/OperatingDay'
        operating_days_printable:
          type: string
        logo_urls:
          type: array
          items:
            type: string
        seating_locations:
          type: array
          items:
            type: string
        accepted_currencies:
          type: array
          items:
            type: string
        parking:
          type: string
        settings:
          type: object
          description: Social media and presentation settings.
        menus:
          type: array
          items:
            $ref: '#/components/schemas/Menu'
    RestaurantInfo:
      type: object
      properties:
        restaurant_name:
          type: string
        brief_description:
          type: string
        full_description:
          type: string
        location_id:
          type: string
        mobile:
          type: string
        address_1:
          type: string
        address_2:
          type: string
        city_town:
          type: string
        state_province:
          type: string
        postal_code:
          type: string
        country:
          type: string
        phone:
          type: string
        fax:
          type: string
        longitude:
          type: number
        latitude:
          type: number
        business_type:
          type: string
        utc_offset:
          type: string
        website_url:
          type: string
  parameters:
    Country:
      name: country
      in: query
      required: true
      description: Country for the search area, ISO 3166-1 alpha-2 (e.g. US).
      schema:
        type: string
    PostalCode:
      name: postal_code
      in: query
      required: false
      description: Limit results to a postal or ZIP code. Required if `city` is not provided.
      schema:
        type: string
    Key:
      name: key
      in: query
      required: false
      description: API key issued from your OpenMenu account.
      schema:
        type: string
    State:
      name: state
      in: query
      required: false
      description: Optional two-letter state or province code to narrow results.
      schema:
        type: string
    City:
      name: city
      in: query
      required: false
      description: Limit results to a city. Required if `postal_code` is not provided.
      schema:
        type: string
  responses:
    RateLimited:
      description: Daily or monthly call credit limit exceeded. Response includes an `upgrade_url`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiEnvelope'
    BillingInactive:
      description: Key is valid structurally but API billing is inactive or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiEnvelope'
    InvalidKey:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiEnvelope'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: key
      description: API key issued from your OpenMenu account, passed as the `key` query parameter on every request. There is no Bearer token or custom header.