Get Namedays

Retrieve name day data for a specific country and date.

GET/api/v1/namedays

Query Parameters

Parameter	Type	Required	Description
`country`	string	No	ISO 3166-1 alpha-2 country code (e.g., `US`, `DE`, `GR`)
`date`	string	No	Specific date in YYYY-MM-DD format
`month`	string	No	Month in YYYY-MM format (returns all days in month)
`calendar_id`	string	No	Filter by specific calendar ID
`limit`	number	No	Maximum results (default: 100, max: 365)
`offset`	number	No	Pagination offset (default: 0)

Example Request

Get namedays for Greece:

curl -X GET 'https://name.birrday.com/api/namedays?country=GR' \
  -H 'x-api-key: YOUR_API_KEY'

Get namedays for a specific date:

curl -X GET 'https://name.birrday.com/api/namedays?country=PL&date=2024-12-25' \
  -H 'x-api-key: YOUR_API_KEY'

Get all namedays for a specific month:

curl -X GET 'https://name.birrday.com/api/namedays?country=GR&month=2024-12' \
  -H 'x-api-key: YOUR_API_KEY'

Response

A successful response returns an array of nameday celebrations:

{
  "namedays": [
    {
      "date": "2024-01-07",
      "names": ["Ιωάννης", "Γιάννης", "Ιωάννα"],
      "feasts": ["Saint John the Baptist"],
      "country": "GR",
      "countryName": "Greece",
      "calendar": "greek-orthodox-2024",
      "tradition": "Orthodox"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}

Response Fields

Field	Type	Description
`date`	string	ISO date (YYYY-MM-DD)
`names`	string[]	List of names in native language
`feasts`	string[]	Associated feast days
`country`	string	Country code
`countryName`	string	Full country name
`calendar`	string	Calendar identifier
`tradition`	string \| null	Calendar tradition (e.g., "Catholic", "Orthodox")

Supported Countries

The following country codes are currently supported:

AT

BG

CY

CZ

DE

ES

FI

FR

GR

HR

HU

IT

LV

PL

RO

RU

SE

SK

UA

Error Responses

Invalid Country Code

{
  "error": "Bad Request",
  "message": "Invalid country code: XX",
  "statusCode": 400
}

Invalid Date Format

{
  "error": "Bad Request",
  "message": "Invalid date format. Use YYYY-MM-DD",
  "statusCode": 400
}

Next: Search Endpoint