locpin API

Introduction

Our Application Program Interface can be integrated easily into your own website or other internet-enabled application.

The API allows your users to create a new locpin, or use an existing one, to give you precise geolocation information for their address.  You can then use this data, for example, as part of a delivery workflow or any process that will benefit from precise location data.

The API exposes a single class, Selector, which has a method open.  You pass this method information from your site to Locpin and a callback provides data from Locpin to your site.

We have made this as simple as possible, but you should consult your IT support or service provider if you are not familiar with the coding techniques involved.  Using our API is subject to the Terms and Conditions that you agreed to when registering for the Locpin service.

Getting started

Please use the Contact Us page to request an API key.  Your request should include your Callback URL. This is the origin of the web page that you are using to interact with locpin - so for example, to add locpin functions to a page called http://yourwebsite.com/ecommerce/basket you would provide http://yourwebsite.com as the Callback URL.

Once we have sent you the API key for your site, you need to include the following scripts in your application:

// styles

<link href="https://locpin.com/JsModules/modal/styles/css/styles.css" rel="stylesheet">

// scripts

<script src="https://locpin.com/jsmodules/modal/src/modal.js"></script>
<script src="https://locpin.com/scripts/ecommerce/constants.js"></script>
<script src="https://locpin.com/scripts/ecommerce/client/locpin-selector.js"></script>

Setup

First, initialise the Locpin Selector once the document has loaded, using your API key:

var key = "your-api-key"

var selector = new Locpin.Selector({
  apiKey: key
});

From here, you can use the Selector's open method to start the selection process, for example by bidning it to an event handler for a button.

var button =  document.querySelector(".your-button");

var yourData = { country: "UK" };

function yourCallback(data) {
  console.log(data);
}

button.addEventListener("click", function() {
  // your code
  selector.open(yourData, yourCallback);
});

Sample usage (using jQuery)

// setup
var key = "your-api-key"
var selector = new Locpin.Selector({
  apiKey: key
});

// provide and use data functions
function getData() {
  return {
    line1: $("input.line-1").text(),

    line2: $("input.line-2").text(),
    city: $("input.city").text(),
    country: $("input.country").text()

  }
}

function useData(data) {
  $("input.locpin-code").text(data.locpin.code);
}

// add event listener
$(".locpin-button").click(function(e) {
  selector.open(getData(), useData);
});

API reference

Selector

class Selector {
    // constructor
    constructor(options: SelectorOptions);
    // properties
    apiKey: string;
    // methods
    open(data: SelectorSendData, callback: (d: SelectorReceiveData) => any);
}

Selector options

interface SelectorOptions {
    apiKey: string;
}

Send data

interface SelectorSendData {
    address: Address;
    apiKey: string;
}

Receive data

interface SelectorReceiveData {
    locpin?: Locpin;
    error: string;
}

Locpin

interface Locpin {
    code: string;
    address?: Address;
}

Address

interface Address {
    line1?: string;
    line2?: string;
    line3?: string;
    line4?: string;
    line5?: string;
    city?: string;
    county?: string;
    postcode?: string;
    country?: string;
}