Integration with Sparq API | Sparq Help Center

Sparq provides an advanced yet an easy API to extend the same filter and search capabilities for your data to your mobile applications, internal CRM or any other app which would want to leverage this capabilities from your app.

Please note that only the stores on "Pro" plan have access to API usage.

Configuration File

The first step toward the integration is to fetch the configuration file for a store. The configuration file for a store is available at the URL https://d354wf6w0s8ijx.cloudfront.net/json/config.json?key=<auth-key>&s=<shop-id>&v=<version>.

As you can see that this path accepts following parameters

key - This is a key which is available on the store dashboard to access this file. The key allows to fetch this file from Sparq servers. If this key is not valid or not provided, the call to this URL will result with a 403 error
s - This param is the ShopID of the store. This is same as the ShopId provided by Shopify. If they key and s do not match, the request to this URL will return a 403 error
v - This is a random alpha-numeric value which defines which version of the configuration you are trying to fetch.

Please note that this file is cached across our CDN across the globe. If you need to fetch latest configuration, just update the version parameter to fetch the latest file.

A sample configuration file is available at https://drive.google.com/file/d/1LZDTWdWKnOY_ltW7x20lpaw7xKUg5yjR/view?usp=sharing

Filter & Search Request

Sparq provides REST API to make filter and search request to its infrastructure. To make the REST API, you need searchToken and collectionId for the data you want to search on. These configuration values are part of the config.json which was downloaded earlier.

Sample REST API

A sample cURL request is shown below. Please note the use of following variables, which are fetched from the config,

app-id
search-token
collection-id

curl --location --request POST 'https://<app-id>-fast.searchtap.net/v2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <search-token>' \
--data-raw '{
    "query": "",
    "fields": [
        "*"
    ],
    "textFacets": [
        "system_top_size",
        "system_bottom_size",
        "system_size",
        "system_upper_size"
    ],
    "highlightFields": [],
    "searchFields": [
        "title",
        "collections",
        "tags",
        "productType"
    ],
    "filter": "priorityScore >= 0",
    "sort": [
        "-publishedTimestamp"
    ],
    "skip": 0,
    "count": 15,
    "collection": "<collection-id>",
    "facetCount": 100,
    "groupCount": -1,
    "typoTolerance": 1,
    "textFacetFilters": {
        "system_top_size": [],
        "system_bottom_size": [],
        "system_size": [],
        "price_price_filter": [],
        "system_upper_size": []
    },
    "numericFacets": {},
    "numericFacetFilters": {},
    "textFacetQuery": null
}'

The API call returns a JSON result with a property results which contains the Shopify product data for the matching results. The detailed JSON response is available at https://drive.google.com/file/d/1LaV5FGm6gYqSNukcUMasCsZ8FhDfy_mR/view?usp=sharing

Security

Sparq secures all API calls to it's infrastructure via secure keys which are unique to each store.

When fetching the config.json, you are required to include key and s (store-id) which both should match for a given store.

When hitting Sparq search servers, you are required to pass searchToken in the Authorisation header for the REST API call, without which it will not return any result.