openapi: 3.0.0
info:
  version: '1.0'
  title: ECL Documentation
  description: |
    # Item Formats
    Depending on the type of list returned, the 'items' will be of varying formats.
    Examples:
    ## Menu
    <pre><code>{
      "name": "Chocolate Croissant",
      "cost": { ... },
      "description": "A tantalizing treat",
      "photo": {
        "url": "http://www.yext-static.com/cms/chocolate-croissant.jpg",
        "height": 250,
        "width": 250
      }
      "calories": {
        "type": "RANGE",
        "calorie": 300,
        "rangeTo": 350
      }
    }</code></pre>

    ## Bio
    <pre><code>
    {
      "name": "Dr. Allan Sicignano",
      "description": "Dr. Allan Sicignano is at the forefront of modern chiropractor techniques...",
      "photo": {"url": "http://www.yext-static.com/cms/dr-allan-sicignano.jpg", "height": 250, "width": 250},
      "education": [
        "Bachelor of Science, Cambridge University",
        "USD Medical School"
      ],
      "certifications": [
        "Chiropractory United",
        "Verified Provider"
      ],
      "services": [
        "Spinal Decompression"
      ],
      "url": "http://www.superchiro.com"
    }
    </code></pre>

    ## Product or Service
    <pre><code>
    {
      "name": "Black & Decker MOUSE Detail Sander with Dust Collection",
      "cost": { ... },
      "photos": [
        {"url": "http://www.yext-static.com/cms/detail-sander.jpg", "height": 250, "width": 250},
        {"url": "http://www.yext-static.com/cms/detail-sander2.jpg", "height": 250, "width": 250}
      ],
      "video": "http://www.youtube.com/watch?v=cGW0XKYeM6o",
      "url": "http://www.kmart.com/deal-of-the-day/dap-120000000279845"
    }
    </code></pre>

    ## Event
    <pre><code>
    {
      "type": "Concert",
      "name": "Gaelic Storm",
      "starts": "2012-08-23T20:00-05",
      "ends": "2012-08-24T00:00-05",
      "description": "$20 tickets.  Doors at 8pm, show at 9pm.",
      "photos": [
        {"url": "http://www.yext-static.com/cms/detail-sander.jpg", "height": 250, "width": 250},
        {"url": "http://www.yext-static.com/cms/detail-sander2.jpg", "height": 250, "width": 250}
      ],
      "video": "http://www.youtube.com/watch?v=jtCEvGxZVIM",
      "url": "http://www.boweryballroom.com/event/125975"
    }
    </code></pre>

    # Item Substructures
    Certain item fields have their own data models, which are described below.

    ## Photo
    <pre><code>
    {
      "url": "http://www.yext-static.com/cms/detail-sander.jpg", "height": 250, "width": 250
    }
    </code></pre>

    ## Cost
    The Cost structure is used in Menus and Products. The customer is able to specify four types of costs:
    1. PRICE: A simple price, optionally "per" something. (e.g., **price** = 9.00, **unit** = per pound)
    2. RANGE: A price range, optionally "per" something. (e.g., **price** = 9.00, **rangeTo** = 12.50, **unit** = each)
    3. NONE: No price specified.
    4. OTHER: Allows the user to enter text. (e.g., **other** = Call for price)

    Seperately, the customer is able to specify **options** on the Cost.  For example:
    1. A Pizza sold in 3 sizes: 
    <pre><code>
    [{"Small", "9.00"}, {"Medium", "11.00"}, {"Large", "13.00"}]
    </code></pre>
    2. Extra toppings on a sandwich:
    <pre><code>
    [{"Bacon", "1.00"}, {"Avocado", "2.00"}]
    </code></pre>

    Example Cost Substructure:
    <pre><code>
    {
      "type": "PRICE",
      "price": "9.50",
      "unit": "Per Sandwich",
      "rangeTo": "",
      "other": "",
      "options": [
        {"name": "Bacon", "price": "1.00", "calorie": 150},
        {"name": "Avocado", "price": "2.00", "calorie": 60}
      ]
    }
    </code></pre>

    ## Calories
    The Calories structure is used in Menus only. You are able to display calories in two ways:
    1. FIXED: A simple calorie count (e.g., **calorie** = 250)
    2. RANGE: A calorie count range (e.g., **calorie** = 250, **rangeTo** = 500)

    Example Calorie Substructure:
    <pre><code>
    {
      "type": "RANGE",
      "calorie": 250,
      "rangeTo": 500
    }
    </code></pre>
servers:
  - url: https://lists.yext-pub.com
paths:
  /lists:
    parameters:
      - $ref: '#/components/parameters/pid'
      - $ref: '#/components/parameters/listingId'
      - $ref: '#/components/parameters/yextId'
      - $ref: '#/components/parameters/listId'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/template'
      - $ref: '#/components/parameters/format'
    get:
      operationId: getEclList
      summary: Get List
      description: |
        Use Get List to retrieve Enhanced Content List (ECL) content in the following use cases:
        1. Fetch the HTML for a specific type of List.
          * **Use listingId, template**
          * Response will be rendered into a template and returned for direct display to the user
        2. Fetch the structured data (JSON) for a specific List
          * **Use listingId, listId**
        3. Fetch the structured data (JSON) for a specific type of List
          * **Use listingId, type**
        4. Fetch the structured data (JSON) for all Lists associated with a listing
          * **Use listingId**
      responses:
        '200':
          $ref: '#/components/responses/GetECLSuccess'
        '400':
          description: Bad request (Incorrect Format)
components:
  parameters:
    pid:
      name: pid
      in: query
      schema:
        type: string
      description: |
        Publisher secure ID. This value will be provided to you.
    listingId:
      name: listingId
      in: query
      schema:
        type: string
      description: |
        Publisher listing ID
    yextId:
      name: yextId
      in: query
      schema:
        type: string
      description: |
        The Yext listing ID
    listId:
      name: listId
      in: query
      schema:
        type: string
      description: |
        ECL ID (Yext-assigned)
    type:
      name: type
      in: query
      schema:
        type: string
        enum:
          - MENU
          - PRODUCTS
          - BIOS
          - EVENTS
      description: |
        Type of lists to return
    template:
      name: template
      in: query
      schema:
        type: string
      description: |
        This parameter specifies the template to use when rendering the List content.
        Yext will provide a list of your available templates. Yext configures each template with the type of data that it accepts -- for example, the template "mobile-menu" may be configured to render all Lists on a listing of type MENU.
        * If no template is specified, all List data will be rendered using a default template
        * Required if fetching HTML
    format:
      name: format
      in: query
      schema:
        type: string
        enum:
          - html
          - json
      description: |
        An alternative way to specify the desired content type of the response
  schemas:
    Section:
      type: object
      properties:
        name:
          type: string
          description: |
            Name of the section.  Here are examples of section names for each type:
            * Menu: [Appetizer, Entree, Dessert]
            * Products: [Kenmore, Craftsman]
            * Bios: [Dentists, Pediatrics]
            * Events: [""]
            * The name field may contain the empty string (""), which indicates that the enclosed items were not assigned to a section.
            Events in a single list will never be divided into multiple sections. All events in a given list will always be in a single section with the name "", in order to preserve the structure used in the other list types.
        description:
          type: string
          description: Description of the section
        items:
          type: array
          description: |
            One of:
            * A list of Menu Items
            * A list of Bios
            * A list of Products
            * A list of Events
            **See examples of each above**
    ECL:
      type: object
      properties:
        id:
          type: string
          description: ID of this list (Yext-assigned)
        name:
          type: string
          description: |
            Name of the list.  Here are examples of list names for each type:
            * Menu: [Breakfast, Lunch, Dinner]
            * Products: [Mens, Womens]
            * Bios: [General Practitioners, Specialists]
            * Events: [Concerts, Workshops]
        description:
          type: string
          description: |
            The label for this list type, as it should appear on the list type's button or link in the PowerListing (e.g., Our Doctors for Bios, Store Events for Events)
            Defaults are:
            * Menu
            * Products
            * Bios
            * Events
        type:
          type: string
          enum:
            - MENU
            - PRODUCTS
            - BIOS
            - EVENTS
        size:
          type: integer
          description: |
            The number of items in the list
        sourceUrl:
          type: string
          description: |
            The URL of the source the list's content is retrieved from
        sections:
          type: array
          description: |
            The list's sections
          items:
            $ref: '#/components/schemas/Section'
  responses:
    GetECLSuccess:
      description: (JSON Format)
      content:
        application/json:
          schema:
            title: GetECLSuccess
            type: object
            properties:
              response:
                $ref: '#/components/schemas/ECL'