NAV Navbar
Code

Tagalys front-end API

curl -X POST \
  https://api.tagalys.com/v1/endpoint \
  -H 'Content-Type: application/json' \
  -d '"JSON Content"'

This document describes the Tagalys front-end API that can be used for integration with your eCommerce store / platform. The Tagalys-developed JavaScript plugin for HTML front-ends also uses this API.

The API works via POST endpoints that accept data in JSON / FormData format.

Authentication & Identification

{
  "identification": {
    "client_code": "client-identification-code",
    "store_id": "store-identification-id",
    "api_key": "client-public-api-key",
  }
}

In Tagalys, a Client can have multiple Stores. To make any search request, both the client and store authentication and identification information should be present in the request body's identification key.

API calls are stateless, and the identification key must be present in all API requests.

Listing Pages

{
  "q": "red pants",
  "qf": {
    "color": ["red"],
    "type": ["pants"]
  }
}

POST https://api.tagalys.com/v1/search

Parameter Type Required Description
q String Required The search term can be two or more characters
qf Filter Object Optional Optional parameter to include filters implied by the query to get more precise search results. Uses the same format as the f parameter described in the Common listing page parameters section.

In addition to this, all of the parameters in the Common listing page parameters section can be used.

Product Listing Pages

POST https://api.tagalys.com/v1/mpages/:listing-page-name

Product Listing Pages are created on the Tagalys Dashboard with a name that can be included in the URL. A page's details can be called using the endpoint that includes that page's name.

The request format is as described in the Common listing page parameters section.

Common listing page parameters

{
  "page": 2,
  "per_page": 24,
  "sort": "introduced_at-desc",
  "f": {
    "length": ["full"],
    "price": {
      "selected_min": 50,
      "selected_max": 100
    }
  },
  "request": [
    "total",
    "results",
    "details",
    "sort_options",
    "filters"
  ]
}

For all listing page APIs like Search and Product Listing Pages, the following parameters can be used.

Parameter Type Required Description
page Integer Optional Requested page number
per_page Integer Optional Number of search results per page
sort String Optional Specify the field and direction to sort results in the format field-direction where direction can be `asc` or `desc`
f String Filter Object

An object with the Tagalys filters selected by the user. The format varies depending on whether the filter is of type checkbox or range.

  • For checkboxes the value is an array of the selected filter IDs
  • For ranges the value is a hash with the following keys:
    • selected_min The starting point of the range selected by the user
    • selected_max The ending point of the range selected by the user
request Array of strings Required

Define what information you want as part of the API response.

  • total The total number of products matching the search / listing page
  • results The product IDs of the matching results
  • details The details of the matching results to enable rendering of the page without making a database call
  • sort_options The available sort options for this list
  • filters The available filters for this list

Response format

{
  "total": 164,
  "results": [
    "8810",
    "...",
    "..."
  ],
  "filters": [
    {
      "id": "price",
      "name": "Price",
      "type": "range",
      "min": 29,
      "max": 329
    },
    {
      "id": "gender",
      "name": "Gender",
      "type": "checkbox",
      "items": [
        {
          "id": "female",
          "name": "Female",
          "count": 93,
          "selected": false
        },
        {
          "id": "male",
          "name": "Male",
          "count": 71,
          "selected": false
        }
      ]
    }
  ],
  "sort_options": [
    {
      "id": "trending",
      "label": "Trending",
      "selected": false
    },
    {
      "id": "introduced_at",
      "label": "Introduced at",
      "selected": true,
      "directions": [
        {
          "direction": "desc",
          "label": "What's new",
          "selected": true
        }
      ]
    },
    {
      "id": "price",
      "label": "Price",
      "selected": false,
      "directions": [
        {
          "direction": "asc",
          "label": "Price-low to high",
          "selected": false
        },
        {
          "direction": "desc",
          "label": "Price-high to low",
          "selected": false
        }
      ]
    }
  ],
  "details": [
    {
      "id": "8810",
      "name": "Lorem ipsum dolor sit amet",
      "sku": "LIDSA",
      "link": "https://www.example.com/lorem-ipsum-dolor-sit-amet",
      "image_url": "https://www.example.com/images/lorem-ipsum-dolor-sit-amet.jpg",
      "price": 49,
      "in_stock": true,
    },
    {...},
    {...}
  ]
}

This is the response format of a generic results page that includes filters, sort options, product IDs, and product details. This information can be used to completely render the results page.