Directory API

The CaribbeanHires business directory is available as a free, read-only JSON API. Use it to show local businesses on your own site or app. No account or key is needed.

Terms of use

• Attribution is required. Show "Data from CaribbeanHires directory" and link back to https://caribbeanhires.com/directory (or to the listing's own page, given as links.web) wherever you display the data. The same text is in every response as meta.attribution and the X-Attribution header.
• Rate limit: 60 requests per minute per IP address. Over the limit you get HTTP 429 and a Retry-After header. Responses are cached for 5 minutes, so there is nothing to gain from polling faster.
• Be gentle with caching: send If-None-Match with the last ETag and you get a small 304 when nothing changed.
• No scraping of the HTML pages. Use this API instead. Automated reading of the website's pages is not allowed.
• Only public information is served: what a business published on its listing page. Listings that are not active are never returned, and the API cannot change anything.

Basics

• Base address: https://caribbeanhires.com/api/directory/v1 (version 1). The data is scoped to the site you ask: CaribbeanHires returns the listings it shows.
• Only GET requests. Any website may call the API from the browser (CORS is open for GET).
• Responses are JSON: data (a resource or a list), links, meta. Each resource has type, id and attributes.
• Errors look like {"errors":[{"status":"404","title":"Not found"}]}.

List businesses

GET https://caribbeanhires.com/api/directory/v1/businesses returns 20 per page, in a stable order (by name). Add ?page=2 for more; the Link header (rel="next") and links.next give the next page.

Filters (all optional, combine freely):

• q: words to look for in the name, tagline, description, services and category
• category: a category slug (includes its sub-categories), see the categories endpoint
• town: a town key such as grenada/st-georges, or a bare town slug, see the towns endpoint
• parish: a parish key or slug
• island: a country code such as VC, LC, GD or BB
• services: one or more service names, as services[]=Leak+repairs or comma separated (up to 5)

curl "https://caribbeanhires.com/api/directory/v1/businesses?q=plumber&island=VC"

{
  "data": [
    {
      "type": "business",
      "id": "quality-plumbing-services",
      "attributes": {
        "name": "Quality Plumbing Services",
        "tagline": "Fast, tidy repairs",
        "description": "...",
        "category": {"slug": "plumbers", "name": "Plumbers"},
        "services": [{"name": "Leak repairs", "description": null}],
        "phone": "784-555-0100",
        "website": "https://example.com",
        "address": {"town": "Kingstown", "parish": "St. George", "island": {"code": "VC", "name": "St. Vincent"}},
        "location": {"latitude": 13.1587, "longitude": -61.2248, "approximate": false},
        "hours_summary": "Mon-Fri 8:00-17:00"
      },
      "links": {"self": "https://caribbeanhires.com/api/directory/v1/businesses/quality-plumbing-services", "web": "https://caribbeanhires.com/directory/quality-plumbing-services"}
    }
  ],
  "links": {"self": "...", "first": "...", "next": "..."},
  "meta": {"version": "v1", "page": 1, "per_page": 20, "total": 1, "last_page": 1,
           "attribution": "Data from CaribbeanHires directory; link back required"}
}

One business

GET https://caribbeanhires.com/api/directory/v1/businesses/{slug} returns the same attributes plus photos. Unknown or inactive listings give 404.

curl "https://caribbeanhires.com/api/directory/v1/businesses/quality-plumbing-services"

Categories and towns

GET https://caribbeanhires.com/api/directory/v1/categories lists the active categories with business_count. GET https://caribbeanhires.com/api/directory/v1/towns lists the towns that have listings, with their island and count.

What is never included

Owner details, private email addresses, enquiries, statistics and internal flags are not part of the API. A phone number, email, website or WhatsApp number appears only if the business published it. Where a business chose to show an approximate area only, its coordinates are rounded exactly as on its page.

Example in JavaScript

const res = await fetch("https://caribbeanhires.com/api/directory/v1/businesses?town=grenada/st-georges");
const { data, meta } = await res.json();
console.log(data.length, meta.attribution);

Questions or a need for more? Contact us.