home / skills / openclaw / skills / apipick-public-holidays

apipick-public-holidays skill

safe

/skills/javainthinking/apipick-public-holidays

This skill helps you retrieve and list public holidays for a country and year using the apipick API.

npx playbooks add skill openclaw/skills --skill apipick-public-holidays

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.3 KB

---
name: apipick-public-holidays
description: Query public holidays for any country and year using the apipick Public Holidays API. Supports 100+ countries identified by ISO 3166-1 alpha-2 country codes. Returns a sorted list of holidays with dates and official names. Use when the user wants to find public holidays for a country, check if a specific date is a holiday, list all national holidays for a given year, or plan around holidays in any country. Requires an apipick API key (x-api-key). Get a free key at https://www.apipick.com.
metadata:
  openclaw:
    requires:
      env:
        - APIPICK_API_KEY
    primaryEnv: APIPICK_API_KEY
---

# apipick Public Holidays

Query public holidays for 100+ countries by ISO country code and year.

## Endpoint

```
GET https://www.apipick.com/api/holidays
```

**Authentication:** `x-api-key: YOUR_API_KEY` header required.
Get a free API key at https://www.apipick.com/dashboard/api-keys

## Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `country` | Yes | ISO 3166-1 alpha-2 code (e.g. `US`, `GB`, `CN`, `DE`, `JP`) |
| `year` | No | 4-digit year (defaults to current year). Range: 1900 to current year + 10 |

```bash
GET /api/holidays?country=US&year=2026
```

## Response

```json
{
  "success": true,
  "code": 200,
  "message": "Holidays retrieved successfully",
  "data": {
    "country": "US",
    "country_name": "United States",
    "year": 2026,
    "total": 11,
    "holidays": [
      {"date": "2026-01-01", "name": "New Year's Day"},
      {"date": "2026-07-04", "name": "Independence Day"},
      {"date": "2026-12-25", "name": "Christmas Day"}
    ]
  },
  "credits_used": 1,
  "remaining_credits": 99
}
```

## Error Codes

| Code | Meaning |
|------|---------|
| 400 | Invalid country code or year |
| 401 | Missing or invalid API key |
| 402 | Insufficient credits |

**Cost:** 1 credit per request

## Usage Pattern

1. Use `$APIPICK_API_KEY` env var as the `x-api-key` header value; if not set, ask the user for their apipick API key
2. Convert a country name to ISO code if the user provides a full name (e.g. "China" → `CN`, "United Kingdom" → `GB`)
3. Make the GET request with `country` and optional `year`
4. Present the holidays as a sorted list with dates and names

See [references/api_reference.md](references/api_reference.md) for full response field descriptions.

Overview

This skill queries public holidays for 100+ countries and years using the apipick Public Holidays API. It returns a sorted list of holiday dates and official names, and requires an apipick API key sent in the x-api-key header. Use it to check holidays by country ISO code or convert a provided country name into the correct ISO 3166-1 alpha-2 code.

How this skill works

The skill accepts an ISO 3166-1 alpha-2 country code (or a country name that it converts to a code) and an optional year. It calls GET https://www.apipick.com/api/holidays with the x-api-key header, parses the JSON response, and returns a sorted list of holidays with date and official name. It handles errors for invalid codes, missing/invalid API keys, and insufficient credits.

When to use it

Find all public or national holidays for a specific country and year.
Check whether a particular date is a public holiday in a country.
Plan events, deadlines, or travel around national holidays.
Aggregate holidays for reporting, calendar imports, or scheduling automation.
Validate holiday-related business logic across multiple countries.

Best practices

Provide an ISO 3166-1 alpha-2 country code when possible (e.g., US, GB, DE) to avoid ambiguity.
Set the API key in the $APIPICK_API_KEY environment variable to avoid repeated prompts.
Specify a year when you need a particular period; otherwise the current year is used by default.
Handle API error codes 400, 401, and 402 explicitly and surface helpful messages to users.
Cache results for the same country/year to reduce API calls and conserve credits.

Example use cases

User asks: “List all public holidays in JP for 2026” — returns sorted dates and names for Japan in 2026.
User asks: “Is 2026-07-04 a holiday in US?” — checks the list and returns yes/no with the holiday name if present.
Planner app requests national holidays for multiple countries to avoid scheduling conflicts.
HR system imports national holidays for the upcoming year to populate leave calendars.
Developer validates a country name by converting it to ISO code then fetching that year’s holidays.

FAQ

What API key is required?

An apipick API key is required and must be sent in the x-api-key header. You can store it in $APIPICK_API_KEY or provide it when prompted.

What country identifiers are supported?

The API accepts ISO 3166-1 alpha-2 country codes (two-letter codes). If you provide a country name, the skill will convert it to the corresponding code when possible.

What years can I query?

You can query years from 1900 up to the current year plus 10. If no year is provided, the current year is used.

What happens if I run out of credits?

The API returns a 402 error for insufficient credits. Handle this by notifying the user and avoiding further requests until credits are replenished.