About

The SHOCAL API is a RESTful service that provides a number of datasets including Stores, Products, POS variables, Deliveries & Analytics. The response data is provided in JSON format.

Parameters & Usage

All API requests must be made over HTTPS.
The content-type header for all requests must be set to application/json.

Our REST API will be served over HTTPS with JSON payloads.

Required Paramseters [GET]

Individual endpoints may have additional parameters

APIKEY

String

Authenticate your request

?apikey={YOUR_KEY_HERE}

Page

Int

If results exceed limit total displayed you can view the next lot of results by increamenting the page numbers

?page=2

Limit

Int

Limit the number of results retuned (Default=20, Maximum=100)

?limit=10

Paramaters temporarily disabled

Latitude & Longitude

String

Filter results by distance (Radius param is required to set radius in miles)

?lat=53.444117&long=-2.36547

Radius

Int

Set a radius in miles

?lat=53.444117&long=-2.36547&radius=10

Events

Live events including sports / comedy

Live shortly!

Discounts

Active vendor discounts

GET URL

https://www.shocal.org/developers/apis/v1/discounts

Parameters

Required

Param	Type	Description
apikey	String	{API_KEY}

Response

Name	Type	Description
Status	Int	HTTP Status
vendorID	Int	Vendor identifier
vendor	string	Shop / Restaurant name
discountPercentage	Int	Total discount available (%)
minSpendRequired	Boolean	Check if there is a minimum spend to get discount
minSpendValue	Int	If minSpendRequired = TRUE then a minimum spend value must be reached
deliveryAreas	String	Directories where discounts will be listed under.

Blogs

List all / individual blogs

GET URL

https://www.shocal.org/developers/apis/v1/blogs

Parameters

Required

Param	Type	Description
apikey	String	{API_KEY}

Optional

Param	Type	Description
blogID	Int	Unique identifier

Response

Name	Type	Description
Status	Int	HTTP Status
vendorID	Int	Vendor identifier
blogID	Int	Blog identifier
title	String	Blog title
body	string	Main content of blog
deliveryAreas	String	Deliverable areas and directories where vendors will be listed under.
created	String [ISO-8601]	Blog added

Trending Items

Popular products that are currently trending in specific postal areas

GET URL

https://www.shocal.org/developers/apis/v1/trending

Parameters

Required

Param	Type	Description
apikey	String	{API_KEY}

Optional

Param	Type	Description
outcode	String	First part of a postcode e.g. {M41} [M41 8AT]

Response

Name	Type	Description
Status	Int	HTTP Status
vendorID	Int	Vendor identifier
productD	Int	Product identifier
name	String	Product name
price	string	Product price
keywords	string	Keywords to describe product
thumbnal	String	Image [Small] (URL)
viewProduct	String	View full product details (URL)

POS

Build custom webhooks to manage orders via your POS system

Live shortly!

Search

Live shortly

Reviews

List all reviews associated with individual vendors

GET URL

https://www.shocal.org/developers/apis/v1/reviews

Parameters

Required

Param	Type	Description
apikey	String	{API_KEY}
vendorID	Int	Unique identifier

Optional

Param	Type	Description
comments	Boolean	TRUE (With comments) FALSE (Without comments)

Response

Name	Type	Description
Status	Int	HTTP Status
vendorID	Int	Unique identifier
blogID	Int	Unique identifier
stars	Int	Stars left by customer (BETWEEN 1-5)
comments	string	Customer feedback
created	String [ISO-8601]	Review added

Product Details

Full product details

GET URL

https://www.shocal.org/developers/apis/v1/product

Parameters

Required

Param	Type	Description
apikey	String	{API_KEY}
vendorID	Int	Unique identifier
productID	Int	Unique identifier

Response

Name	Type	Description
Status	Int	HTTP Status
vendorID	Int	Vendor identifier
productID	Int	Product identifier
name	String	Product name
description	String	Description
price	Int	Price (GBP)
preparationTime	Int	Time taken to prepare before for collection
category	Int	Menu category
categorySub	Int	Menu sub-category
thumbnail	String	Image [Small] (URL)
heroImg	String	Main profile image [Large] (URL)
created	String [ISO-8601]	When item was first added
modified	String [ISO-8601]	Last time product was updated

Name	Type	Description
Status	Int	HTTP Status
vendorID	Int	Vendor identifier
productID	Int	Product identifier
name	String	Product name
description	String	Description
price	Int	Price (GBP)
thumbnail	String	Image [Small] (URL)
created	String [ISO-8601]	When item was first added
modified	String [ISO-8601]	Last time product was updated
viewProduct	String	View full product details (URL)

List Vendors

GET URL

https://www.shocal.org/developers/apis/v1/list-vendors

Parameters

Required

Param	Type	Description
apikey	String	{API_KEY}

Response

Name	Type	Description
Status	Int	HTTP Status
vendorID	Int	Vendor identifier
vendorName	String	Name of vendor (shop / restaurant / service)
outcode	String	First part of the postcode
vendorProfile	String	view full profile details
modified	String [ISO-8601]	Last updated

Featured Vendors

GET URL

https://www.shocal.org/developers/apis/v1/featured

Parameters

Required

Param	Type	Description
apikey	String	{API_KEY}

Response

Name	Type	Description
Status	Int	HTTP Status
vendorID	Int	Vendor identifier
vendorName	String	Name of vendor (shop / restaurant / service)
outcode	String	First part of the postcode
vendorProfile	String	Url to full profile details
modified	String [ISO-8601]	Last updated

Vendors

Vendor Profile

GET URL

https://www.shocal.org/developers/apis/v1/vendors?vendorID=8

Parameters

Required

Param	Type	Description
apikey	String	{API_KEY}
vendorID	Int	Unique identifier

Response

Name	Type	Description
Status	Int	HTTP Status
vendorID	Int	Vendor identifier
vendorName	String	Name of vendor (shop / restaurant / service)
tagLine	String	Additional information about the vendor
addressLine1	String	Address
addressLine2	String	Address
city	String	Address
postcode	String	Address
outcode	String	First part of the postcode
longitude	Int	Geolocation
latitude	Int	Geolocation
telephone	String	Primary contact number
categories	String	Quick categories associated with vendor services
storeThumbnail	String	Profile picture
deliveryAreas	String	Deliverable areas and directories where vendors will be listed under.
openingHours	String	Opening hours for each day of the week
ratingScore	Int	Overall rating score
ratingReviewTotal	Int	Total reviews
ratingReviewsURL	String	View reviews associated with vendor
socialMedia	String	Links to social media associated with vendor
products	String	Url to vendor active products associated with vendor
profile	String	Url to vendor profile on the Shocal Web Platform
modified	String [ISO-8601]	Last updated

Sign In

API Usage

Requests

To call the API, make a HTTP GET request to the following URL:

https://www.shocal.org/developers/apis/v1/vendors?apikey=YOUR_API_KEY

Responses

A sample JSON response is below::

{
                "vendorID": "8",
                "storeName": "Flowers By Siobhan",
                "tagLine" : "Family run florist",
                "addressLine1" : "196 Church Road",
                "addressLine2": "Urmston",
                "city" : "Manchester",
                "postcode" : "M41 9DX",
                "outcode" : "M41",
                "longitude" : "-2.365475",
                "latitude" : "53.444117",
                "telephone" : "0161 478 8024",
                "categories" : "flowers,occasions,bundles",
                "storeThumbnail" : "https://www.shocal.org/business/stores/images/8/8.jpg"
                "deliveryAreas" : "M1,M11,M12,M13,M14,M15,M16,M17,M18,M19,M2,M20,M21,M22,M23,M24,M25,M26,M27,M28,M29,M3,M30,M31,M32,M33,M34,M35,M38,M4,M40,M41,M43,M44,M45,M46,M5,M50,M6,M60,M61,M7,M8,M9,M90,M99,WA14,WA15",
                "openingHours":[
                    "Monday"    : "09:00 - 17:00",
                    "Tuesday"   : "09:00 - 17:00",
                    "Wednesday" : "09:00 - 17:00",
                    "Thursday"  : "09:00 - 17:00",
                    "Friday"    : "09:00 - 17:00",
                    "Saturday"  : "09:00 - 17:00",
                    "Sunday"    : "closed"
                ],
                "ratings":[
                    "ratingScore"       :  "5.0",
                    "ratingReviewTotal" :  171,
                    "ratingReviewsURL"  :  "https://www.shocal.org/developers/apis/v1/reviews?vendorID=8&apikey={YOUR_KEY}"
                ],
                "socialMedia":[
                    "Facebook"   :  "https://www.facebook.com/flowersbysiobhan.flowers/",
                    "Instragram" :  "https://www.instagram.com/flowersbysiobhan/",
                    "Twitter"    :  "https://twitter.com/flowerbysiobhan",
                ],
                "URLs":[
                    "products" : "https://www.shocal.org/developers/apis/v1/products?vendorID=8&apikey={YOUR_KEY}",
                    "profile" : "https://www.shocal.org/business/?sid=8"
                ]
}

Request API access key

To access Shocal API services please send a request to enquiries@shocal.org along with your contact details and reasons for access.

HTTP status codes

The functional API specifications for each API define the specific format and values returned. In addition to this, the table below includes common errors that may be thrown by the surrounding API framework.

Response	Message	Comments	Sample JSON
200	OK	Requested data appears	{ “message”: “parameters: []” }
400	Bad Request	If the incoming request body or parameters do not conform with the API standards which describes the API you will see this error.	{ “message”: “Missing required request parameters: []” }
401	Forbidden	Missing authentication token or unsupported HTTP method (GET/POST)	{ “message”: “Missing authentication token or unsupported API method or resource”}
401	Forbidden	Access denied	{ “message”: “Access denied”}
429	Too Many Requests	This happens when the throttling limit of a client is exceeded	{ “message”: “Too Many Requests” }
429	Null	This happens when the collective throttling limit for the API is exceeded	{ “message”: “null” }
500, 502	Bad Gateway	This can be returned when an unexpected error occurs with the service	{ “message”: “Internal server error” }
504	Gateway Timeout	This happens when there is a network connection problem within the layers of the API fulfillment stack	{ “message”: “Gateway Timeout” }

Usage Plans and Throttling Limits

We have introduced limits on API usage rates in terms of requests per second. This applies to both individual clients and collective usage for all clients.

A client’s limit is set based on the usage plan that the client is subscribed to
As clients access the API at the same time, there is an overall limit on how many requests are allowed per second in order to protect the service

These two scenarios will return an HTTP status code of 429 as specified in the common errors section.

Standard Plan: 1 request per second per endpoint

🍪 Cookie Notice

About

Parameters & Usage

Required Paramseters [GET]

APIKEY

Page

Limit

Latitude & Longitude

Radius

Events

Discounts

GET URL

Parameters

Required

Response

Blogs

GET URL

Parameters

Required

Optional

Response

Trending Items

GET URL

Parameters

Required

Optional

Response

POS

Search

Reviews

GET URL

Parameters

Required

Optional

Response

Product Details

GET URL

Parameters

Required

Response

Menu

GET URL

Parameters

Required

Response

List Vendors

GET URL

Parameters

Required

Response

Featured Vendors

GET URL

Parameters

Required

Response

Vendors

GET URL

Parameters

Required

Response

Sign In

API Usage

Requests

Responses

Request API access key

HTTP status codes

Usage Plans and Throttling Limits