Locally Headless API SDK

Introduction

A Javascript SDK for the Locally.com Headless API. This library is built with Javascript developers in mind, but it also works with TypeScript.

Note: This SDK is in beta and is not ready for production

Features

• Supports Node.js 14+.
• Ships with CommonJS and ES Modules.
• Works in server and browser environments.

Installing

npm install @locally-com/lcly-js-sdk

Client

To set up the client we will authenticate with a token as follows:

import LCLY from "@locally-com/lcly-js-sdk" // ESM
// const LCLY = require('@locally-com/lcly-js-sdk').default // CommonJS
const client = new LCLY("{{ MY_TOKEN }}")

Examples

To see the full list of API endpoints this SDK supports and their implementation, please review the dist/mjs/api/ directory: https://www.npmjs.com/package/@locally-com/lcly-js-sdk?activeTab=code

Initialize a shopper session

Initialize the shopper session and validate your product and UPC combination.

import LCLY from "@locally-com/lcly-js-sdk"

const client = new LCLY("{{ MY_TOKEN }}")

async function main() {
    const result = await client.conversion().get('start', {
        upc: "{{ UPC }}",
        product_id: {{ PRODUCT_ID }},
        company_id: {{ COMPANY_ID }}
    })

    console.log(result)
}

main()

The response contains a validated UPC and its geographical location.

{
  "success": true,
  "data": {
    "style": "999",
    "company_id": 999,
    "upc": "000000000000",
    "company_name": "ACME Outfitters Chicago",
    "initial_store_id": 999,
    "company_logo": "image.jpg",
    "user_geo": {
      "lat": "41.8756719",
      "lng": "-87.6243469",
      "city_label": "Chicago, IL",
      "country": "US",
      "distance_unit": "mi"
    }
  }
}

Locate a product at multiple stores

With the response from the initialization example, you can now use the validated UPC and geographic coordinates to return a list of stores that stock the item.

import LCLY from "@locally-com/lcly-js-sdk"

const client = new LCLY("{{ MY_TOKEN }}")

async function main() {
    const result = await client.conversion().get('store_data', {
        company_id: {{ COMPANY_ID }},
        upc: "{{ UPC }}",
        map_center_lat: "{{ LAT }}",
        map_center_lng: "{{ LNG }}",
        map_distance_unit: "{{ UNIT }}",
        map_distance_diag: "{{ DISTANCE }}"
    })

    console.log(result)
}

main()

This response contains a list of stores that have the validated UPC in stock nearest to the shopper's geographical location.

{
  "success": true,
  "data": {
    "all_upcs_carried": [
       000000000000,
       ...
    ],
    "markers": [
      {
        "id": 37175,
        "name": "ACME Outfitters Chicago",
        "lat": "41.91136867",
        "lng": "-87.67771437",
        "address": "15 ACME Ave",
        "city": "Chicago",
        "state": "IL",
        "zip": "60647",
        "phone": "(555) 697-7381",
        "country": "US",
        "company_id": 999,
        "image": "image.jpg",
        "vendor_id": "",
        "user_distance": 0,
        "stock_status": 3,
        "stocking_product": 1,
        "stocking_variant": 1,
        "acquisition_options": {
      		bopis: 1,
        	ropis: 1
        },
        "disclaimer": "Item is in Stock!",
        "dow": 0,
        "display_dow": [
          {
            "bil_hrs": "7am-8pm",
            "label": "Monday",
            "day_index": 0
          }
        ],
        "today_hours": "7am-8pm",
        "hours_known": 1,
        "is_open": 1,
        "next_open": "",
        "is_closing_soon": 0,
        "phone_link": "tel:+15556977381",
        "is_tmp_closed": 0,
        "status_class": "success",
        "status_label": "Open",
        "qoh": 10,
        "stock_status_constants": [
          {
            "key": "PRODUCT_YES_VARIANT_YES_BIL_YES",
            "value": "Item is in Stock!"
          }
        ],
        "feature_constants": [
          {
            "key": "DELIVERY_AVAILABLE",
            "value": "Same-day Local Delivery Available"
          },
          {
            "key": "IN_STORE_PICKUP_AVAILABLE",
            "value": "Store Pickup Available"
          }
        ],
        "web_address": "https:\/\/www.acmeco.com"
      },
      ...
    ],
    "total_marker_count": 100
  }
}

Tracking a product at a specific store

If you are interested in ongoing product availability for a specific store, you can query the conversion/store_data endpoint in single store mode.

Start by recording the specific data.markers[].id of a multi-store result (please review the prior example if needed). We can target a particular store by setting the store ID as value for the only_store_id query parameter.

import LCLY from "@locally-com/lcly-js-sdk"

const client = new LCLY("{{MY_TOKEN}}")

async function main() {
    const result = await client.conversion().get('store_data', {
        only_store_id: {{ STORE_ID }},
        company_id: {{ COMPANY_ID }},
        upc: "{{ UPC }}",
        map_distance_unit: "{{ UNIT }}",
        map_distance_diag: "1"
    })

    console.log(result)
}

main()

The response is nearly identical to the multi-store request example, except that only one marker is returned.

Manually handling location and persisting a session

All of the Locally Headless API endpoints will automatically attempt to geolocate the shopper based on their location on the first request. However, it is possible to set an alternative location prior to initialization and persist it for subsequent requests by utilizing sessions.

In this example we are asking the API for suggestions of locations matching the term "chicago".

import LCLY from "@locally-com/lcly-js-sdk"

const client = new LCLY("{{MY_TOKEN}}")

async function main() {
    const result = await client.location().get('suggest', {
        query: "Chicago"
    })

    console.log(result)
}

main()

The response includes coordinates for locations that match the term "chicago".

{
  "success": true,
  "data": {
    "query": "chicago",
    "suggestions": [
      {
        "value": "Chicago, Illinois, United States",
        "postcode": "",
        "data": {
          "lat": 41.875562,
          "lng": -87.624421,
          "relevance": 1
        }
      },
      {
        "value": "Chicagon, Michigan, United States",
        "postcode": "",
        "data": {
          "lat": 46.095231,
          "lng": -88.507357,
          "relevance": 0.96
        }
      }
    ],
    "from": [
      "40.0292888",
      "-105.3100174"
    ],
    "session": {
      "id": "abc999"
     }
  }
}

We can utilize the session ID, coordinates and URL-encoded location name returned in the location/suggest payload to switch the shopper's location for the duration of their session.

import LCLY from "@locally-com/lcly-js-sdk"

const client = new LCLY("{{MY_TOKEN}}")

async function main() {
    const result = await client.location().get('switch', {
        lat: "41.875562",
        lng: "-87.624421",
        location_change_to_string: "Chicago,+Illinois,+United+States"
    }, {
      'Locally-Api-Session-Id': "abc999",
    })

    console.log(result)
}

main()

Response:

{
  "success": true,
  "data": {
    "city_label": "Chicago, IL",
    "country": "US",
    "zip_label": "60604",
    "postal_code": "60604",
    "lat": "41.87758900",
    "lng": "-87.62818000",
    "source": "region",
    "base_url": "/in/chicago-il",
    "distance_unit": "mi",
    "session": {
      "id": "abc999"
     }
  }
}

The response confirms a successful location change has been applied to this shopper's location. To persist the location in subsequent requests, we can now go through the normal initialization workflow, being mindful to pass the session ID:

import LCLY from "@locally-com/lcly-js-sdk"

const client = new LCLY("{{ MY_TOKEN }}")

async function main() {
    const result = await client.conversion().get('start', {
        upc: "{{ UPC }}",
        product_id: {{ PRODUCT_ID }},
        company_id: {{ COMPANY_ID }}
    },{
        'Locally-Api-Session-Id': "abc999",
    })

    console.log(result)
}

main()