📘

API Docs

Detailed technical documentation is available here - Mapping API Documentation

Overview

This document defines the Mapping API methods available for Hawksearch v4.0 and the associated objects. This documentation is intended for clients’ development teams to create and maintain the Hawksearch v4.0 indexes. Use this API to create and maintain custom facets sort order on search and landing pages.

Domains

Hawksearch has three environments available: Development, Test and a load-balanced Production. When using the search API methods in this document, the following domains can be used to access each environment after your engine has been set-up in that environment.

🚧

Before You Begin

Please ensure that your client-specific endpoints are configured before implementing any API integrations. Please refer to this article to learn more about client-specific endpoints and reach out to our CSD team for any questions.

Development

client-specific URL: https://enginename.dev.index-na.hawksearch.com

Configurations for an engine in this location are maintained in the HawkSearch Workbench at dev.hawksearch.net.

Test

client-specific URL: https://enginename.test.index-na.hawksearch.com

Configurations for an engine in this location are maintained in the HawkSearch Workbench at test.hawksearch.net.

Production

client-specific URL: https://enginename.index-na.hawksearch.com

Configurations for an engine in this location are maintained in the HawkSearch Workbench at dashboard-na.hawksearch.com.

Mapping API Methods

Upsert

The Upsert method is used to insert mapping records. The mapping records are often categories or departments. There is a limit of 125 mapping objects that can be sent in a request. This method can be called multiple times to accommodate more than 125.

Request

Parameters

Retrieve Mapping

This method can be used to verify the mapping that has been created.

Request

Parameters

Response

Mapping Object

Mapping API Examples

Use this API to create and maintain custom facets sort order on search and landing pages.

Following operations are provided by Hawksearch mapping API:

1. Upsert to add new or update existing mappings
2. View Mappings to list the mappings in a json format

General Notes:

Ensure that the header contains the Hawksearch Key for all the operations:
Request headers must contain the Hawksearch API Key as follows:
Format: X-HawkSearch-ApiKey : {your engine API ke}
Example: X-HawkSearch-ApiKey : 12345678-9ABC-DEF0-1234-56789ABCDEF0

Upsert the mapping in a POST request

POST /api/mapping/upsert
{
    "indexName": "elasticdemo.20210903.113840",
    "Mappings": [
        {
            "Field": "size-property",
            "Label": "Extra Small",
            "Value": "Extra Small",
            "SortOrder": 1
        },
        {
            "Field": "size-property",
            "Label": "Small",
            "Value": "Small",
            "SortOrder": 2
        },
        {
            "Field": "size-property",
            "Label": "Medium",
            "Value": "Medium",
            "SortOrder": 3
        },
        {
            "Field": "size-property",
            "Label": "Large", 
            "Value": "Large",
            "SortOrder": 4
        }
    ]
}

Below API request lists the mappings

Request

POST /api/mapping/
{
  "indexName": "elasticdemo.20210903.113840",
  "Field":"size-property"
}

Response

[
    {
        "Mapping": {
            "Field": "size-property",
            "Label": "Large",
            "SortOrder": "4"
        },
        "Field": "size-property",
        "Value": "Large"
    },
    {
        "Mapping": {
            "Field": "size-property",
            "Label": "Small",
            "SortOrder": "2"
        },
        "Field": "size-property",
        "Value": "Small"
    },
    {
        "Mapping": {
            "Field": "size-property",
            "Label": "Medium",
            "SortOrder": "3"
        },
        "Field": "size-property",
        "Value": "Medium"
    },
    {
        "Mapping": {
            "Field": "size-property",
            "Label": "Extra Small",
            "SortOrder": "1"
        },
        "Field": "size-property",
        "Value": "Extra Small"
    }
]