Blipstar API

Want to access your store data programmatically? Blipstar has a very simple API (Application Programming Interface) whereby you supply a map co-ordinate and it returns a list of your nearest stores. How does it work? Your web application fires off a basic HTTP request and receives a response in JSON format. It's then up to you to manipulate the data as required.

1. Activating the API

  1. Login to your Blipstar account
  2. Go to Settings > General and find the API section
  3. Set the API access option to Yes
  4. You can, optionally, limit access to your data to specific IP addresses. Just enter your server's IP address (if it's more than one server separate each IP address with a comma)
  5. Leave the IP access field blank to allow API calls to be made from any machine
  6. Save your settings

2. Sending an API Request

The code on your server sends a simple HTTP GET request.

Example 1
https://viewer.blipstar.com/api/?uid=[YOURACCOUNTID]&lat=37.774&lng=-122.419&results=5

The above example is asking for the nearest 5 results to map location 37.774,-122.419 (San Francisco)

Example 2
https://viewer.blipstar.com/api/?uid=[YOURACCOUNTID]&search=New+York&radius=100&results=25&tag=flagship&country=usa

The above example is requesting stores within 100km of New York containing the tag Flagship and only in the USA (so Canadian stores would not be returned). In addition a maximum of 25 results should be returned.

A few things to note:
  • You can either send "lat" and "lng" parameters OR a "search" parameter if you want it geocoded
  • Empty fields are omitted from the JSON response
  • Online-only stores are excluded from results (i.e. the API only returns stores with a geographic location)
  • Because the API calls can be restricted by IP address, no authentication or API key is required
  • A maximum of 250 results can be returned in a single response
  • Your account ID (UID) is displayed on the menu page when you login
  • API calls can be made using HTTP as well as HTTPS

Request Parameters

ParameterExplanationExample
uidYour unique Blipstar account id2857242
latLatitude (decimal degrees, -90 to 90)87.512454
lngLongitude (decimal degrees, -180 to 180)163.922620
searchLocation to search for (if not supplying lat and lng)Orlando,FL
resultsNumber of results to return3
Optional parameters...
radiusSearch radius (in km). Return stores located with [radius] km of lat-lng.50
countryLimit results to stores within this country (uses each store's Country field)canada
stateLimit results to stores within this state/province (uses each store's State field)bc
tagLimit results to stores with this tag (uses store's Tag field - if more than one, separate with a comma)menswear
tag2Limit results to stores with this tag from your second group of tags


3. Receiving an API Response

The API returns JSON, containing a simple array of store locations. If no matching stores were found the array will be empty. The following example contains two results.

Example (success)
[
  {
    "n": "Wonderland Store",
    "s": "MA",
    "c": "United States",
    "ad": "10 Made Up Drive, MA, 91867, United States",
    "pc": "91867",
    "p": "(555) 123 4567",
    "w": "www.madeupsite.com/wonderland/product2",
    "m1": "Now Open Sundays!",
    "dist": "6.5",
    "lat": 42.310687,
    "lng": -71.180077
  },
  {
    "n": "Super World",
    "s": "MA",
    "c": "United States",
    "ad": "1943 Nowhere Street, MA, 92665, United States",
    "pc": "92665",
    "p": "(555) 765 4321",
    "dist": "17.2",
    "lat": 42.83453,
    "lng": -70.72347
  }
]
Example (error)
{
    "error": "Invalid UID (it should be your unique Blipstar account ID)"
}

Response Fields

FieldsValue
nStore name
distDistance (from search location)
adAddress
pcPostal/Zip code
sState/Province
cCountry
pPhone number
eEmail
wWebsite
m1Misc 1
m2Misc 2
m3Misc 3
m4Misc 4
iIcon
lgLogo
ptyPriority
monMonday opening times
tueTuesday opening times
wedWednesday opening times
thuThursday opening times
friFriday opening times
satSaturday opening times
sunSunday opening times
tgTag(s)
tg2Second group of Tag(s)
tg3Third group of Tag(s)
rgSales regions (postal codes)

We've made the API as simple to set up as possible but if you do encounter any issues just let us know.

Providing store locator solutions since 2006.   Share: Linkedin  |  Twitter  |  Google+  |  Facebook  |  Pinterest