openapi: 3.1.0
info:
  title: OpenMenu Analytics Search 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: Search
  description: Find restaurants, menu items, and sample menus by location and term.
paths:
  /search.php:
    get:
      operationId: search
      summary: Search Restaurants And Menu Items
      description: Find restaurants, menu items, and sample menus by location and search term. At least one of `postal_code` or `city` is required, along with `country`. Use `s=sample` for sandbox data.
      tags:
      - Search
      parameters:
      - $ref: '#/components/parameters/Key'
      - name: s
        in: query
        required: true
        description: Search term for a restaurant or menu item. Use `sample` for sandbox data.
        schema:
          type: string
      - name: offset
        in: query
        required: false
        description: Page index for paginated results (0-based). Maximum page index is 10.
        schema:
          type: integer
          minimum: 0
          maximum: 10
          default: 0
      - name: r
        in: query
        required: false
        description: Limit results to restaurants only.
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: mi
        in: query
        required: false
        description: Limit results to menu items only.
        schema:
          type: integer
          enum:
          - 0
          - 1
      - $ref: '#/components/parameters/PostalCode'
      - $ref: '#/components/parameters/City'
      - $ref: '#/components/parameters/State'
      - $ref: '#/components/parameters/Country'
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingInactive'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  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
    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
    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
    City:
      name: city
      in: query
      required: false
      description: Limit results to a city. Required if `postal_code` is not provided.
      schema:
        type: string
  schemas:
    SearchResponse:
      type: object
      properties:
        api:
          $ref: '#/components/schemas/ApiEnvelope'
        result:
          type: object
          properties:
            restaurants:
              type: array
              items:
                $ref: '#/components/schemas/RestaurantSummary'
            items:
              type: array
              items:
                $ref: '#/components/schemas/MenuItem'
            menus:
              type: array
              items:
                $ref: '#/components/schemas/Menu'
    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'
    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
    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.
    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
    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'
  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.