Name: GlobalOps Calendar API: Holidays and Workdays by Country
Brand: visionwell
SKU: api-visionwell-globalops-calendar
Availability: InStock
Author: API Market

binbin7418-dotcom

# GlobalOps Calendar API

## Overview

GlobalOps Calendar turns a list of countries and a date range into a workday plan for each country. One endpoint plans a batch of up to 25 countries, another plans a single country, and a health endpoint reports service status. Each country comes back with the public holidays in the range, exact counts of total days, weekend days and workdays, an optional add-workdays date, and a World Bank country profile.

It is built for operations, payroll and project teams that work across borders and need one calendar answer per country. Holiday data comes from the open-source python-holidays dataset (MIT License) and covers 248 countries and territories for 2019 to 2032. Country indicators come from World Bank Open Data (CC BY 4.0), and each value is reported with its year.

## Features

*   **3 endpoints**: batch planning, single-country planning and a health check.
*   **Batch planning**: up to 25 countries and a range of up to 367 days in one call.
*   **Exact counts**: total days, weekend days, public holidays and workdays for the range.
*   **Add-workdays**: optional projection that lists every day skipped and why.
*   **Country profiles**: capital, region, income level, GDP, GDP per capita and population, each with its year.
*   **Per-country results**: a country without holiday data comes back as `not_covered` and the rest of the batch still plans.
*   **Data sources**: python-holidays (MIT License) and World Bank Open Data (CC BY 4.0).
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **Global payroll teams**: compare working days per country for the same pay period.
*   **Project managers**: see which offices are closed during a delivery window.
*   **Logistics operators**: project dates across several countries in one call.
*   **Sales and support leaders**: plan coverage around regional public holidays.
*   **Market research**: pair calendar data with World Bank country context.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/visionwell/globalops-calendar
```

### Authentication

Every request must include your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Plan a batch of countries

Plans up to 25 countries over one date range, with an optional add-workdays projection.

**Method:** `POST`

**Endpoint:** `/plan/batch`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| countries | body | ISO 3166-1 alpha-2 country codes, e.g. ["US", "DE", "JP"]. | array of strings | Yes | - | - |
| start | body | Start of the range, in YYYY-MM-DD format. | string | Yes | - | - |
| end | body | End of the range, in YYYY-MM-DD format. The range can be up to 367 days. | string | Yes | - | - |
| addWorkdays | body | Optional projection with `from` (YYYY-MM-DD) and `days`. | object | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/visionwell/globalops-calendar/plan/batch' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "countries": [
    "US",
    "DE",
    "JP",
    "CN"
  ],
  "start": "2026-12-21",
  "end": "2026-12-31",
  "addWorkdays": {
    "from": "2026-12-23",
    "days": 5
  }
}'
```

**Example Response (200 OK):**

```json
{
  "scope": "GlobalOps Calendar's holiday and workday verdicts are built on the open-source holiday dataset bundled into HolidayCal (python-holidays, MIT License): per-country holiday lists match the dataset entry...",
  "results": [
    {
      "country": "US",
      "errors": [],
      "status": "ok",
      "range": {
        "start": "2026-12-21",
        "end": "2026-12-31",
        "totalDays": 11
      },
      "holidays": [
        {
          "date": "2026-12-25",
          "name": "Christmas Day",
          "localName": "Christmas Day",
          "dayOfWeek": "Fri",
          "onWeekend": false
        }
      ],
      "counts": {
        "totalDays": 11,
        "weekendDays": 2,
        "publicHolidaysOnWeekdays": 1,
        "publicHolidaysOnWeekends": 0,
        "workdays": 8
      },
      "addWorkdays": {
        "from": "2026-12-23",
        "days": 5,
        "resultDate": "2026-12-31",
        "skippedCount": 3,
        "skipped": [
          {
            "date": "2026-12-25",
            "reason": "public holiday: Christmas Day"
          },
          {
            "date": "2026-12-26",
            "reason": "weekend"
          }
        ],
        "note": "Counts workdays strictly after (before, for negative days) the start date, skipping Saturdays, Sundays and public-type holidays only."
      },
      "profile": {
        "code": "USA",
        "iso2": "US",
        "name": "United States",
        "capital": "Washington D.C.",
        "region": "North America",
        "incomeLevel": "High income",
        "lendingType": "Not classified"
      },
      "indicators": {
        "gdp": {
          "year": 2025,
          "value": 30769700000000
        },
        "gdpPerCapita": {
          "year": 2025,
          "value": 90026.5163005744
        },
        "population": {
          "year": 2025,
          "value": 341784857
        }
      },
      "indicatorUnits": {
        "gdp": "current US$",
        "gdpPerCapita": "current US$",
        "population": "people"
      }
    },
    {
      "country": "DE",
      "errors": [],
      "status": "ok",
      "range": {
        "start": "2026-12-21",
        "end": "2026-12-31",
        "totalDays": 11
      },
      "holidays": [
        {
          "date": "2026-12-25",
          "name": "Christmas Day",
          "localName": "Erster Weihnachtstag",
          "dayOfWeek": "Fri",
          "onWeekend": false
        },
        {
          "date": "2026-12-26",
          "name": "Second Day of Christmas",
          "localName": "Zweiter Weihnachtstag",
          "dayOfWeek": "Sat",
          "onWeekend": true
        }
      ],
      "counts": {
        "totalDays": 11,
        "weekendDays": 2,
        "publicHolidaysOnWeekdays": 1,
        "publicHolidaysOnWeekends": 1,
        "workdays": 8
      },
      "addWorkdays": {
        "from": "2026-12-23",
        "days": 5,
        "resultDate": "2026-12-31",
        "skippedCount": 3,
        "skipped": [
          {
            "date": "2026-12-25",
            "reason": "public holiday: Christmas Day"
          },
          {
            "date": "2026-12-26",
            "reason": "weekend"
          }
        ],
        "note": "Counts workdays strictly after (before, for negative days) the start date, skipping Saturdays, Sundays and public-type holidays only."
      },
      "profile": {
        "code": "DEU",
        "iso2": "DE",
        "name": "Germany",
        "capital": "Berlin",
        "region": "Europe & Central Asia",
        "incomeLevel": "High income",
        "lendingType": "Not classified"
      },
      "indicators": {
        "gdp": {
          "year": 2025,
          "value": 5050922925047.05
        },
        "gdpPerCapita": {
          "year": 2025,
          "value": 60496.4350820414
        },
        "population": {
          "year": 2025,
          "value": 83491249
        }
      },
      "indicatorUnits": {
        "gdp": "current US$",
        "gdpPerCapita": "current US$",
        "population": "people"
      }
    }
  ],
  "summary": {
    "requested": 4,
    "ok": 4,
    "notCovered": 0,
    "errored": 0,
    "totalWorkdays": 34,
    "totalPublicHolidays": 3,
    "totalDaysPlanned": 44,
    "notCoveredCountries": []
  }
}
```

#### 2. Plan one country

Plans one country over a date range.

**Method:** `POST`

**Endpoint:** `/plan/single`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| country | body | ISO 3166-1 alpha-2 country code, e.g. "US". | string | Yes | - | - |
| start | body | Start of the range, in YYYY-MM-DD format. | string | Yes | - | - |
| end | body | End of the range, in YYYY-MM-DD format. The range can be up to 367 days. | string | Yes | - | - |
| addWorkdays | body | Optional projection with `from` (YYYY-MM-DD) and `days`. | object | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/visionwell/globalops-calendar/plan/single' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "country": "CN",
  "start": "2026-09-28",
  "end": "2026-10-07"
}'
```

**Example Response (200 OK):**

```json
{
  "scope": "GlobalOps Calendar's holiday and workday verdicts are built on the open-source holiday dataset bundled into HolidayCal (python-holidays, MIT License): per-country holiday lists match the dataset entry...",
  "archive": {
    "country": "CN",
    "errors": [],
    "status": "ok",
    "range": {
      "start": "2026-09-28",
      "end": "2026-10-07",
      "totalDays": 10
    },
    "holidays": [
      {
        "date": "2026-10-01",
        "name": "National Day",
        "localName": "国庆节",
        "dayOfWeek": "Thu",
        "onWeekend": false
      },
      {
        "date": "2026-10-02",
        "name": "National Day",
        "localName": "国庆节",
        "dayOfWeek": "Fri",
        "onWeekend": false
      },
      {
        "date": "2026-10-03",
        "name": "National Day",
        "localName": "国庆节",
        "dayOfWeek": "Sat",
        "onWeekend": true
      }
    ],
    "counts": {
      "totalDays": 10,
      "weekendDays": 2,
      "publicHolidaysOnWeekdays": 5,
      "publicHolidaysOnWeekends": 1,
      "workdays": 3
    },
    "profile": {
      "code": "CHN",
      "iso2": "CN",
      "name": "China",
      "capital": "Beijing",
      "region": "East Asia & Pacific",
      "incomeLevel": "Upper middle income",
      "lendingType": "IBRD"
    },
    "indicators": {
      "gdp": {
        "year": 2025,
        "value": 19498039388042.6
      },
      "gdpPerCapita": {
        "year": 2025,
        "value": 13861.970224368
      },
      "population": {
        "year": 2025,
        "value": 1406585000
      }
    },
    "indicatorUnits": {
      "gdp": "current US$",
      "gdpPerCapita": "current US$",
      "population": "people"
    },
    "dataScopeNote": "China scope: the dataset carries China's statutory holiday spans (including the substituted days off created by adjusted weekends) and HolidayCal's make-up working days are applied, so workday verdict..."
  }
}
```

#### 3. Health

Returns the service status.

**Method:** `GET`

**Endpoint:** `/health`

**Parameters:** None.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/visionwell/globalops-calendar/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "service": "GlobalOps Calendar",
  "version": 1
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. Check the parameter table for the endpoint. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but your subscription does not allow this request, for example an endpoint outside your plan. |
| 404 | Not Found | The path does not exist, or the resource you asked for was not found. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Slow down and retry, honouring the `Retry-After` header. |
| 500 | Internal Server Error | Something went wrong while processing the request. Retry after a short wait. |
| 503 | Service Unavailable | The service or its upstream data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

Every plan allows up to 10 requests per second. Subscription plans also have a monthly call quota shown on the pricing page. Sending more than 10 requests per second returns `429 Too Many Requests`. Throttle your client to stay under 10 requests per second, back off and retry when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **What happens for a country with no holiday data?**

    That country returns `status: not_covered` with the code `NOT_COVERED`. It is a normal 200 response, and no workday verdict is computed for it.

*   **Which holidays reduce the workday count?**

    Only public-type holidays. Observances, school days and bank-only entries do not reduce it.

*   **How current are the World Bank values?**

    Each value is the most recent one reported for that country and comes with its year. Values that were not reported are null.

*   **Is this legal or payroll advice?**

    No. The API reports calendar facts and country context, and verdicts follow the dataset rather than a government gazette.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Plan up to 25 countries in one call: public holidays, exact workday counts, add-workdays dates and World Bank country profiles as JSON.

GlobalOps Calendar API: Holidays and Workdays by Country