Headless Query API reference

POST "https://{{domainkey}}.store-{{locationkey}}.ometria.services/api/query"
{
    "request_id"    : {{ request_id }},         /* optional (String or Number) */
    "format"        : {{ json_or_html }},       /* optional (String), default: "json" */
    "elements"      : [{{ element_list }}],     /* required (Array) */
    "user": {
        "uid"           : {{ uid }},            /* required (String) */
        "sid"           : {{ sid }},            /* required (String) */
        "ip_address"    : {{ ip_address }}      /* optional (String) */
    },
    "context": {
        "category_id"   : {{ category_id }},    /* optional (String) */
        "product_id"    : {{ product_id }},     /* optional (String) */
        "page_id"       : {{ page_id }},        /* optional (String) */
        "page_url"      : {{ page_url }},       /* optional (String) */
        "user_agent"    : {{ user_agent }},     /* optional (String) */
        "language_id"   : {{ language_id }},    /* optional (String) */
        "currency_id"   : {{ currency_id }}     /* optional (String) */
        "warehouse_id"  : {{ warehouse_id }}    /* optional (String) */
    },
    "args": {
        {{ key_1 }}     : {{ value_1 }},
        {{ key_2 }}     : {{ value_2 }},
        {{ key_n }}     : {{ value_n }}
    },
    "response_options"  : {
        "fields": {
            "products"      : [{{ field_list }}]    /* optional (Array) */
        }
    }
}

request_id

Optional.

A string or number containing a unique identifier.

The API will return this value back with the response.

format

Optional.

A string defining the format of the content returned.

The allowed values are html or json.

If format is not specified then a default value of json is used.

elements

Required.

An array with a list of element identifiers.

Each element identifier must correspond to those elements defined in the Ometria website personalisation feature.

{
   "elements"  : ["category", "category_recs"]
}

user

Required.

An object containing key information about the current site visitor.

These include:

• uid (Required): A string containing a unique id associated with the current visitor.
• sid (Required): A string containing a unique id associated with the current visit session.
• ip_address (Optional): A string containing the IP address associated with the current visit session.

📘

Note

The uid and sid codes are generated by Ometria and returned with each response.

The application ingesting the response is expected to persist the uid as a permanent cookie and sid as a session cookie.

If no uid or sid are detected then Ometria generates new IDs and returns with the response.

The only time the uid and sid should be omitted is when a user visits the site for the first time.

The ip_address is required if you want to use merchandising insights.

context

Optional.

An object containing key information about the current request.

These include:

• page_url (Optional): The full url corresponding to the web page that the end user is currently viewing.
  • We recommend that you always include this field.
• user_agent (Optional): The web browser user agent.
  • We recommend that you always include this field.
• category_id (Optional): The id of the category for the current page.
  • This is required for category pages.
  • We recommend including this field in every request.
• product_id (Optional): The id of the product for the current product detail page.
• page_id(Optional): The id of the content page for the current page.
  • This is required on product detail pages.
• language_id (Optional): This is only required if multiple languages are defined.
• currency_id (Optional): This is only required if multiple currencies are defined.
• warehouse_id (Optional): This is only required if you have multiple warehouses and would like the stock data to reflect one specific warehouse rather than the sum of all of them.

args

Optional.

In addition to the standard parameters, args allows you to define your own custom parameters in the form of key-value pairs.

E.g. segmentation values, additional product or category details, etc.

Use these to create even more granular personalisation.

{
   "args": {
       "site_section"      : "womens",
       "weather"           : "cold",
       "user_location"     : "london",
       "user_type"         : "new",
       "user_affinity"     : "brands"
   }
}

response_options

Optional.

An object containing response definitions and options.

fields

Optional.

An object containing response definitions for fields returned.

products

Optional.

An array of strings that define which product fields should be returned in the request.

We recommend only asking for the fields you need - this is to minimise response sizes.

{
   "response_options"  : {
       "fields": {
           "products"  : ["id", "sku", "prices"]
       }
   }
}

If response_options > fields > products is not defined then all fields will be returned, which may result in a large payload.

The allowed fields are:

• id
• sku
• stock
• url
• titles
• abstracts
• media
• pricing
• features
• variants
• properties
• tags
• created
• modified
• published

product_features

Optional.

An array of strings that define which features should be returned.

This is used in conjunction with the products array and is only applied if "features" is included in the products list.

If product_features is not defined then all features will be returned in the response.

We recommend only asking for the features you need - this is to minimise response sizes.

{
   "response_options"  : {
       "fields": {
           "products"          : ["id", "sku", "prices", "features"],
           "product_features"  : ["brand", "material"]
       }
   }
}