Holiday API

Holiday API — Countries

Lists supported countries with ISO codes (alpha-2, alpha-3, numeric), spoken languages, currencies, flag image URLs, weekend days, and state/province subdivisions.

GitHub OpenAPI

Documentation

📖
Documentation
https://holidayapi.com/docs

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/holidays/refs/heads/main/openapi/holidays-api-openapi.yml

Examples

📝
Example
https://raw.githubusercontent.com/api-evangelist/holidays/refs/heads/main/examples/holidays-list-countries-example.json

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/holidays/refs/heads/main/json-schema/holidays-country-schema.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/holidays/refs/heads/main/json-structure/holidays-country-structure.json

Other Resources

🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/holidays/refs/heads/main/capabilities/holidays-countries.yaml
🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/holidays/refs/heads/main/json-ld/holidays-context.jsonld

OpenAPI Specification

holidays-api-openapi.yml Raw ↑ 
openapi: 3.0.3

info:
  title: 'Holiday API'
  description: 'Holidays are hard. We make them easy.'
  termsOfService: 'https://holidayapi.com/terms'
  contact:
    name: 'Holiday API'
    email: '[email protected]'
  version: '1.0'

servers:
  - url: 'https://holidayapi.com'
    description: 'Holiday API v1'

tags:
  - name: Holidays
    description: 'Public holidays and observances for countries, states, and provinces.'
  - name: Countries
    description: 'Country metadata, codes, languages, currencies, and subdivisions.'
  - name: Languages
    description: 'Supported languages for retrieving localized holiday names.'
  - name: Workdays
    description: 'Working / business day calculations honoring country workweeks and holidays.'

paths:
  /v1/holidays:
    get:
      operationId: listHolidays
      tags:
        - Holidays
      summary: 'List Holidays'
      description: 'Retrieves a list of public holidays and observances for countries, states and provinces.'
      externalDocs:
        description: 'Developer Documentation'
        url: 'https://holidayapi.com/docs'
      parameters:
        - name: key
          description: 'Your API key.'
          required: true
          in: query
          schema:
            type: string
            format: uuid
          example: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
        - name: country
          description: 'For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. For subdivisions, ISO 3166-2 format. Accepts up to 10 comma separated values.'
          required: true
          in: query
          schema:
            type: string
          example: US
        - name: year
          description: 'ISO 8601 format'
          required: true
          in: query
          schema:
            type: integer
            format: int32
          example: 2015
        - name: month
          description: '1 or 2 digit month (1-12)'
          required: false
          in: query
          schema:
            type: integer
            format: int32
          example: 7
        - name: day
          description: '1 or 2 digit day (1-31 depending on the month). Must be used with month.'
          required: false
          in: query
          schema:
            type: integer
            format: int32
          example: 4
        - name: public
          description: 'Return only public holidays.'
          required: false
          in: query
          schema:
            type: boolean
            default: false
          example: true
        - name: subdivisions
          description: 'Return state / province holidays alongside countrywide holidays. Available on our States & Provinces plan.'
          required: false
          in: query
          schema:
            type: boolean
            default: false
          example: true
        - name: search
          description: 'Search holidays by name.'
          required: false
          in: query
          schema:
            type: string
            minimum: 5
          example: 'Independence Day'
        - name: language
          description: 'ISO 639-1 format (with exceptions).'
          required: false
          in: query
          schema:
            type: string
          example: en
        - name: previous
          description: 'Return the first day of holidays that occur before the specific date. month and day are required. Cannot be used with upcoming.'
          required: false
          in: query
          schema:
            type: boolean
          example: true
        - name: upcoming
          description: 'Return the first day of holidays that occur after the specific date. month and day are required. Cannot be used with previous.'
          required: false
          in: query
          schema:
            type: boolean
          example: true
        - name: format
          description: 'Response format.'
          required: false
          in: query
          schema:
            type: string
            default: json
            enum:
              - csv
              - json
              - php
              - tsv
              - yaml
              - xml
          example: json
        - name: pretty
          description: 'Prettifies results to be more human-readable.'
          required: false
          in: query
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: 'Success! Everything is A-OK.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/holidays'

  /v1/countries:
    get:
      operationId: listCountries
      tags:
        - Countries
      summary: 'List Countries'
      description: 'Retrieves a list of countries with their states and provinces.'
      externalDocs:
        description: 'Developer Documentation'
        url: 'https://holidayapi.com/docs'
      parameters:
        - name: key
          description: 'Your API key.'
          required: true
          in: query
          schema:
            type: string
            format: uuid
          example: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
        - name: country
          description: 'Return only the country with the specified code.'
          required: false
          in: query
          schema:
            type: string
          example: US
        - name: search
          description: 'Search countries by code and name.'
          required: false
          in: query
          schema:
            type: string
            minimum: 2
          example: United
        - name: public
          description: 'Return only countries that have public holidays.'
          required: false
          in: query
          schema:
            type: boolean
            default: false
          example: true
        - name: format
          description: 'Response format.'
          required: false
          in: query
          schema:
            type: string
            default: json
            enum:
              - csv
              - json
              - php
              - tsv
              - yaml
              - xml
          example: json
        - name: pretty
          description: 'Prettifies results to be more human-readable.'
          required: false
          in: query
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: 'Success! Everything is A-OK.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/countries'

  /v1/languages:
    get:
      operationId: listLanguages
      tags:
        - Languages
      summary: 'List Languages'
      description: 'Retrieves a list of supported languages.'
      externalDocs:
        description: 'Developer Documentation'
        url: 'https://holidayapi.com/docs'
      parameters:
        - name: key
          description: 'Your API key.'
          required: true
          in: query
          schema:
            type: string
            format: uuid
          example: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
        - name: language
          description: 'Return only the languages with the specified code.'
          required: false
          in: query
          schema:
            type: string
          example: US
        - name: search
          description: 'Search languages by code and name.'
          required: false
          in: query
          schema:
            type: string
            minimum: 2
          example: United
        - name: format
          description: 'Response format.'
          required: false
          in: query
          schema:
            type: string
            default: json
            enum:
              - csv
              - json
              - php
              - tsv
              - yaml
              - xml
          example: json
        - name: pretty
          description: 'Prettifies results to be more human-readable.'
          required: false
          in: query
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: 'Success! Everything is A-OK.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/languages'

  /v1/workday:
    get:
      operationId: getWorkday
      tags:
        - Workdays
      summary: 'Get Workday'
      description: "Calculates the workday (based on a country's workweek) that occurs a given number of days after a date."
      externalDocs:
        description: 'Developer Documentation'
        url: 'https://holidayapi.com/docs'
      parameters:
        - name: key
          description: 'Your API key.'
          required: true
          in: query
          schema:
            type: string
            format: uuid
          example: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
        - name: country
          description: 'For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. For subdivisions, ISO 3166-2 format. Accepts up to 10 comma separated values.'
          required: true
          in: query
          schema:
            type: string
          example: US
        - name: start
          description: 'The date (in YYYY-MM-DD format) from which to begin counting.'
          required: true
          in: query
          schema:
            type: string
            format: date
          example: '2015-07-01'
        - name: days
          description: 'Number of working / business days to advance (positive integer) or retrogress (negative integer) from start.'
          required: true
          in: query
          schema:
            type: integer
            format: int32
          example: 7
        - name: format
          description: 'Response format.'
          required: false
          in: query
          schema:
            type: string
            default: json
            enum:
              - csv
              - json
              - php
              - tsv
              - yaml
              - xml
          example: json
        - name: pretty
          description: 'Prettifies results to be more human-readable.'
          required: false
          in: query
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: 'Success! Everything is A-OK.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/workday'

  /v1/workdays:
    get:
      operationId: getWorkdays
      tags:
        - Workdays
      summary: 'Get Workdays'
      description: "Calculates the number of workdays (based on a country's workweek) that occur between a given date range."
      externalDocs:
        description: 'Developer Documentation'
        url: 'https://holidayapi.com/docs'
      parameters:
        - name: key
          description: 'Your API key.'
          required: true
          in: query
          schema:
            type: string
            format: uuid
          example: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
        - name: country
          description: 'For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. For subdivisions, ISO 3166-2 format. Accepts up to 10 comma separated values.'
          required: true
          in: query
          schema:
            type: string
          example: US
        - name: start
          description: 'The date (in YYYY-MM-DD format) from which to begin counting.'
          required: true
          in: query
          schema:
            type: string
            format: date
          example: '2015-07-01'
        - name: end
          description: 'The date (in YYYY-MM-DD format) to count until.'
          required: true
          in: query
          schema:
            type: string
            format: date
          example: '2015-07-10'
        - name: format
          description: 'Response format.'
          required: false
          in: query
          schema:
            type: string
            default: json
            enum:
              - csv
              - json
              - php
              - tsv
              - yaml
              - xml
          example: json
        - name: pretty
          description: 'Prettifies results to be more human-readable.'
          required: false
          in: query
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: 'Success! Everything is A-OK.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/workdays'

components:
  schemas:
    response:
      type: object
      required:
        - status
        - requests
      properties:
        status:
          type: integer
          format: int32
          example: 200
        requests:
          type: object
          required:
            - used
            - available
            - resets
          properties:
            used:
              type: integer
              format: int32
              example: 136
            available:
              type: integer
              format: int32
              example: 864
            resets:
              type: string
              example: '2019-09-01 00:00:00'
        error:
          type: string
          example: 'An error has occurred.'
        warning:
          type: string
          example: 'An warning has occurred.'

    weekday:
      type: object
      required:
        - date
        - observed
      properties:
        date:
          type: object
          required:
            - name
            - numeric
          properties:
            name:
              type: string
              example: 'Saturday'
            numeric:
              type: string
              example: '6'
        observed:
          type: object
          required:
            - name
            - numeric
          properties:
            name:
              type: string
              example: 'Friday'
            numeric:
              type: integer
              format: int32
              example: 5

    holiday:
      type: object
      required:
        - name
        - date
        - observed
        - public
        - country
        - uuid
        - weekday
      properties:
        name:
          type: string
          example: 'Independence Day'
        date:
          type: string
          format: date
          example: '2015-07-04'
        observed:
          type: string
          format: date
          example: '2015-07-03'
        public:
          type: boolean
          example: true
        country:
          type: string
          example: US
        uuid:
          type: string
          format: uuid
          example: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
        weekday:
          $ref: '#/components/schemas/weekday'
        subdivisions:
          type: array
          items:
            type: string
            example:
              - 'US-FL'
              - 'US-TX'

    country:
      type: object
      required:
        - code
        - name
        - codes
        - languages
        - currencies
        - flag
        - subdivisions
        - weekend
      properties:
        code:
          type: string
          example: US
        name:
          type: string
          example: United States of America
        codes:
          type: object
          required:
            - 'alpha-2'
            - 'alpha-3'
            - numeric
          properties:
            alpha-2:
              type: string
              minimum: 2
              maximum: 2
              example: US
            alpha-3:
              type: string
              minimum: 3
              maximum: 3
              example: USA
            numeric:
              type: integer
              format: int32
              example: 840
        languages:
          type: array
          items:
            type: string
            minimum: 2
            example: en
        currencies:
          type: array
          items:
            type: object
            required:
              - alpha
            properties:
              alpha:
                type: string
                minimum: 3
                maximum: 3
                example: USD
        flag:
          type: string
          example: https://holidayapi.com/images/flags/64/us.png
        subdivisions:
          type: array
          items:
            type: object
            required:
              - code
              - name
              - languages
            properties:
              code:
                type: string
                minimum: 2
                example: US-TX
              name:
                type: string
                example: Texas
              languages:
                type: array
                items:
                  type: string
                  minimum: 2
                  example: en
        subdivisions:
          type: array
          items:
            type: object
            required:
              - code
              - name
              - languages
            properties:
              code:
                type: string
                minimum: 4
                example: US-TX
              name:
                type: string
                example: Texas
              languages:
                type: array
                items:
                  type: string
                  minimum: 2
                  example:
                    - en
              subdivisions:
                type: array
                items:
                  type: object
                  required:
                    - code
                    - name
                    - languages
                  properties:
                    code:
                      type: string
                      minimum: 4
                      example: US-TX
                    name:
                      type: string
                      example: Texas
                    languages:
                      type: array
                      items:
                        type: string
                        minimum: 2
                        example:
                          - en
        weekend:
          type: array
          items:
            type: object
            required:
              - name
              - numeric
            properties:
              name:
                type: string
                example: 'Sunday'
              numeric:
                type: integer
                format: int32
                example: 7

    language:
      type: object
      required:
        - code
        - name
      properties:
        code:
          type: string
          example: en
        name:
          type: string
          example: 'English'

    holidays:
      allOf:
        - $ref: '#/components/schemas/response'
        - type: object
          required:
            - holidays
          properties:
            holidays:
              type: array
              items:
                $ref: '#/components/schemas/holiday'

    countries:
      allOf:
        - $ref: '#/components/schemas/response'
        - type: object
          required:
            - countries
          properties:
            countries:
              type: array
              items:
                $ref: '#/components/schemas/country'

    languages:
      allOf:
        - $ref: '#/components/schemas/response'
        - type: object
          required:
            - languages
          properties:
            countries:
              type: array
              items:
                $ref: '#/components/schemas/language'

    workday:
      allOf:
        - $ref: '#/components/schemas/response'
        - type: object
          required:
            - date
            - weekday
          properties:
            date:
              type: string
              format: date
              example: '2015-07-13'
            weekday:
              $ref: '#/components/schemas/weekday'

    workdays:
      allOf:
        - $ref: '#/components/schemas/response'
        - type: object
          required:
            - workdays
          properties:
            date:
              type: integer
              format: int32
              example: 10