Authentication

Learn how to authenticate your API requests using your API key.

API Key Authentication

All API requests must include your API key as a query parameter. Your API key identifies your application and is used to track usage and enforce rate limits.

Code Examples

curl -X GET \
  "https://www.shocal.org/developers/apis/v1/vendors?apikey=YOUR_API_KEY&limit=10" \
  -H "Accept: application/json"

const response = await fetch(
  'https://www.shocal.org/developers/apis/v1/vendors?apikey=YOUR_API_KEY&limit=10',
  {
    method: 'GET',
    headers: { 'Accept': 'application/json' }
  }
);

const data = await response.json();
console.log(data);

<?php
$apiKey = 'YOUR_API_KEY';
$url = "https://www.shocal.org/developers/apis/v1/vendors?apikey={$apiKey}&limit=10";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

import requests

api_key = 'YOUR_API_KEY'
url = f'https://www.shocal.org/developers/apis/v1/vendors?apikey={api_key}&limit=10'

response = requests.get(url)
data = response.json()
print(data)

Authentication Errors

Rate Limits

Understand our rate limiting policies to ensure reliable API access.

Current Limits

To ensure fair usage and maintain service quality, we enforce the following rate limits:

Rate Limit Headers

Each API response includes headers to help you track your rate limit status:

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
    "status": 429,
    "message": "Too Many Requests"
}

Increasing Your Limits

Need higher rate limits? Contact us at enquiries@shocal.org to discuss enterprise plans with custom limits.

Error Handling

Understand API error responses and how to handle them gracefully.

Error Response Format

{
    "status": 401,
    "message": "Access denied"
}

HTTP Status Codes

Get API Access

Request access to the SHOCAL API to start building with local business data.

List Vendors

Retrieve a paginated list of all active vendors on the platform.

Vendor Profile

Retrieve detailed information about a specific vendor.

Menu

Retrieve menu items for a specific vendor.

Product

Retrieve details for a specific product.

Reviews

Retrieve customer reviews for a specific vendor.

Discounts

Retrieve active discounts and promotions.

Blogs

Retrieve blog posts and articles.

Trending

Retrieve trending and popular products based on recent views.

Featured

Retrieve featured and promoted vendors.