Name Days & Calendar API

Overview

The Name Days API provides a secure proxy to Typesense search functionality, allowing authenticated applications to search through a comprehensive database of Finnish, Swedish, Sámi, Orthodox, and even pet name days. All requests are authenticated using API tokens, logged for analytics, and rate-limited per organization.

Authentication

All API requests require authentication using an organization-specific API token.

API Token Authentication

API tokens are unique identifiers that start with ndt_ and are tied to specific organizations. Include your API token in the Authorization header:

Authorization: Bearer ndt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0...

Today's Name Days Endpoint

Get all name days for the current date without needing to specify any parameters. This endpoint automatically fetches today's names and groups them by type.

Request

No parameters required - the endpoint automatically uses the current date.

Example Request

curl -X GET https://nimipaivarajapinta.fi/api/namedays/today \
  -H "Authorization: Bearer ndt_your_api_token_here"

Response Format

{
  "success": true,
  "date": {
    "day": 10,
    "month": 9,
    "year": 2025,
    "formatted": "10.9.2025"
  },
  "total_count": 7,
  "name_days": [
    {
      "id": "123",
      "name": "Sinikka",
      "type": "suomi",
      "gender": "nainen",
      "day": 10,
      "month": 9
    },
    {
      "id": "124",
      "name": "Sini",
      "type": "suomi",
      "gender": "nainen",
      "day": 10,
      "month": 9
    },
    {
      "id": "125",
      "name": "Erik",
      "type": "ruotsi",
      "gender": "mies",
      "day": 10,
      "month": 9
    }
  ],
  "name_days_by_type": {
    "suomi": [
      {"id": "123", "name": "Sinikka", "type": "suomi", "gender": "nainen", "day": 10, "month": 9},
      {"id": "124", "name": "Sini", "type": "suomi", "gender": "nainen", "day": 10, "month": 9}
    ],
    "ruotsi": [
      {"id": "125", "name": "Erik", "type": "ruotsi", "gender": "mies", "day": 10, "month": 9}
    ]
  },
  "response_time_ms": 32,
  "_meta": {
    "authenticated_user": null,
    "organization_id": 5,
    "organization_name": "Example Org",
    "auth_type": "api_token",
    "timestamp": "2025-09-10T18:30:00Z"
  }
}

Search Parameters

Request Parameters

Available Filter Fields

Examples

curl -X GET https://nimipaivarajapinta.fi/api/namedays/today \
  -H "Authorization: Bearer ndt_your_api_token_here"

curl -X POST https://nimipaivarajapinta.fi/api/typesense/collections/namedays/documents/search \
  -H "Authorization: Bearer ndt_your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "type:=suomi && gender:=nainen",
    "per_page": 20,
    "sort_by": "month:asc,day:asc"
  }'

curl -X POST https://nimipaivarajapinta.fi/api/typesense/collections/namedays/documents/search \
  -H "Authorization: Bearer ndt_your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "day:=24 && month:=12",
    "sort_by": "name:asc"
  }'

curl -X GET "https://nimipaivarajapinta.fi/api/typesense/collections/namedays/documents/search?q=Maria&query_by=name" \
  -H "Authorization: Bearer ndt_your_api_token_here"

const API_TOKEN = 'ndt_your_api_token_here';

async function getTodaysNameDays() {
  const response = await fetch('https://nimipaivarajapinta.fi/api/namedays/today', {
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`
    }
  });

  if (!response.ok) {
    throw new Error(`API Error: ${response.status}`);
  }

  return await response.json();
}

// Example usage
getTodaysNameDays()
  .then(data => {
    console.log(`Today is ${data.date.formatted}`);
    console.log(`${data.total_count} names celebrate today:`);
    
    // Display by type
    for (const [type, names] of Object.entries(data.name_days_by_type)) {
      console.log(`\n${type}:`);
      names.forEach(n => console.log(`  - ${n.name} (${n.gender})`));
    }
  })
  .catch(error => console.error('Failed to fetch today\'s names:', error));

const API_TOKEN = 'ndt_your_api_token_here';
const API_URL = 'https://nimipaivarajapinta.fi/api/typesense/collections/namedays/documents/search';

async function searchNameDays(query, filters) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      q: query || '*',
      filter_by: filters,
      per_page: 50,
      sort_by: 'name:asc',
      facet_by: 'type,gender,month'
    })
  });

  if (!response.ok) {
    throw new Error(`API Error: ${response.status}`);
  }

  return await response.json();
}

// Example: Find all Swedish male names
searchNameDays('*', 'type:=ruotsi && gender:=mies')
  .then(results => {
    console.log(`Found ${results.found} Swedish male names`);
    results.hits.forEach(hit => {
      const doc = hit.document;
      console.log(`${doc.name} - ${doc.day}.${doc.month}`);
    });
  })
  .catch(error => console.error('Search failed:', error));

import requests
from datetime import datetime

API_TOKEN = 'ndt_your_api_token_here'

def get_todays_name_days():
    headers = {
        'Authorization': f'Bearer {API_TOKEN}'
    }
    
    response = requests.get(
        'https://nimipaivarajapinta.fi/api/namedays/today',
        headers=headers
    )
    response.raise_for_status()
    return response.json()

# Example usage
today_data = get_todays_name_days()
print(f"Today is {today_data['date']['formatted']}")
print(f"Total names celebrating: {today_data['total_count']}")

# Display names by type
for name_type, names in today_data['name_days_by_type'].items():
    print(f"\n{name_type.capitalize()} names:")
    for name_info in names:
        print(f"  - {name_info['name']} ({name_info['gender']})")

import requests
import json

API_TOKEN = 'ndt_your_api_token_here'
API_URL = 'https://nimipaivarajapinta.fi/api/typesense/collections/namedays/documents/search'

def search_name_days(query='*', filters=None, page=1, per_page=50):
    headers = {
        'Authorization': f'Bearer {API_TOKEN}',
        'Content-Type': 'application/json'
    }
    
    payload = {
        'q': query,
        'query_by': 'name',
        'page': page,
        'per_page': per_page,
        'sort_by': 'name:asc',
        'facet_by': 'type,gender,month'
    }
    
    if filters:
        payload['filter_by'] = filters
    
    response = requests.post(API_URL, json=payload, headers=headers)
    response.raise_for_status()
    return response.json()

# Example 1: Find all Orthodox names
orthodox_names = search_name_days('*', 'type:=ortod')
print(f"Found {orthodox_names['found']} Orthodox names")

# Example 2: Find names for a specific date
july_names = search_name_days('*', 'day:=15 && month:=7')
for hit in july_names['hits']:
    doc = hit['document']
    print(f"{doc['name']} ({doc['type']}, {doc['gender']})")

# Example 3: Search with pagination
page = 1
while True:
    results = search_name_days('*', 'type:=koira', page=page, per_page=100)
    print(f"Page {page}: {len(results['hits'])} dog names")
    
    if page >= results.get('out_of', 1):
        break
    page += 1

Response Structure

Successful Response

{
  "found": 2847,
  "hits": [
    {
      "document": {
        "id": "123",
        "name": "Maria",
        "type": "suomi",
        "gender": "nainen",
        "day": 15,
        "month": 8,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      "highlight": {
        "name": {
          "snippet": "Maria"
        }
      }
    }
  ],
  "facet_counts": [
    {
      "field_name": "type",
      "counts": [
        {"value": "suomi", "count": 1250},
        {"value": "ruotsi", "count": 980}
      ]
    }
  ],
  "page": 1,
  "out_of": 285,
  "search_time_ms": 12,
  "_meta": {
    "response_time_ms": 45,
    "authenticated_user": null,
    "organization_id": 5,
    "organization_name": "Example Org",
    "auth_type": "api_token",
    "timestamp": "2024-01-15T12:30:00Z"
  }
}

Response Fields

Error Handling

Common Error Responses

{
  "statusCode": 401,
  "statusMessage": "Authentication required - provide JWT or API token"
}

{
  "statusCode": 401,
  "statusMessage": "Invalid API token"
}

{
  "statusCode": 401,
  "statusMessage": "API token has expired"
}

{
  "statusCode": 401,
  "statusMessage": "API token is inactive"
}

{
  "statusCode": 401,
  "statusMessage": "Organization is inactive"
}

{
  "statusCode": 400,
  "statusMessage": "Invalid search parameters"
}

{
  "statusCode": 500,
  "statusMessage": "Search proxy failed"
}

Calendar API

Beyond name days, the API also exposes Finnish calendar metadata: holidays, flag days and notable days. Each is stored in its own Typesense collection alongside the existing namedays collection. Authentication, analytics and per-organization usage tracking work identically to the name day endpoints.

Collections

Common document fields

Every calendar document carries a full ISO date plus pre-derived helpers so you can filter by year, month or week without parsing the date string client-side:

Calendar Search Endpoint

An opinionated convenience endpoint that returns one record per date in a range, merging holidays, flag days and notable days, with optional locale formatting (Finnish or Swedish month and weekday names, numeric or written-out date format).

Request Body

Example Request

curl -X POST https://nimipaivarajapinta.fi/api/calendar/search \
  -H "Authorization: Bearer ndt_your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-02-01",
    "to": "2026-02-28",
    "lang": "fi",
    "date_format": "long",
    "weekday": "short",
    "holiday_list": "short"
  }'

Example Response

{
  "success": true,
  "results": [
    {
      "date": "2026-02-05",
      "display_date": "To 5. helmikuuta 2026",
      "year": 2026, "month": 2, "day": 5,
      "weekday": 4,
      "weekday_label": "To",
      "holiday": null,
      "flag_day": {
        "name": "J.L. Runebergin päivä",
        "flags": ["fi"],
        "flag_urls": { "fi": "/flags/fi.svg" }
      },
      "notable_day": null
    },
    {
      "date": "2026-02-14",
      "display_date": "La 14. helmikuuta 2026",
      "year": 2026, "month": 2, "day": 14,
      "weekday": 6,
      "weekday_label": "La",
      "holiday": null,
      "flag_day": null,
      "notable_day": { "name": "Ystävänpäivä" }
    }
  ],
  "_meta": {
    "from": "2026-02-01",
    "to": "2026-02-28",
    "lang": "fi",
    "count": 2,
    "response_time_ms": 28,
    "organization_id": 5,
    "organization_name": "Example Org",
    "auth_type": "api_token",
    "timestamp": "2026-05-04T09:00:00Z"
  }
}

Calendar Collection Endpoints

Three thin Typesense passthrough endpoints, one per collection. They mirror the existing /api/typesense/collections/namedays/documents/search proxy: same auth model, same per-organization analytics, and they preserve the standard Typesense response shape so the official client libraries work transparently.

Request Body

Pass any standard Typesense SearchParameters as JSON. Typical fields:

Example Request — short-list holidays in 2026

curl -X POST https://nimipaivarajapinta.fi/api/typesense/collections/holidays/documents/search \
  -H "Authorization: Bearer ndt_your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "query_by": "name_fi,name_sv",
    "filter_by": "year:=2026 && in_short_list:=true",
    "sort_by": "date:asc",
    "per_page": 50
  }'

Example with typesense-js

import Typesense from 'typesense'

const client = new Typesense.Client({
  nodes: [{
    host: 'nimipaivarajapinta.fi',
    port: 443,
    protocol: 'https',
    path: '/api'
  }],
  apiKey: 'ndt_your_api_token_here',
  connectionTimeoutSeconds: 5
})

const result = await client
  .collections('holidays')
  .documents()
  .search({
    q: '*',
    query_by: 'name_fi,name_sv',
    filter_by: 'year:=2026 && in_short_list:=true',
    sort_by: 'date:asc',
    per_page: 50
  })

Filter Examples

Response Shape

Identical to a Typesense search response. The proxy adds a _meta object alongside hits, found, page etc.:

{
  "hits": [
    {
      "document": {
        "id": "1714817349-abc123",
        "date": "2026-02-05",
        "year": 2026, "month": 2, "day": 5,
        "weekday": 4, "iso_week": 6,
        "name_fi": "J.L. Runebergin päivä",
        "name_sv": "Runebergsdagen",
        "flags": ["fi"],
        "created_at": "2026-04-30T12:00:00Z",
        "updated_at": "2026-04-30T12:00:00Z"
      },
      "highlight": {},
      "highlights": []
    }
  ],
  "found": 22,
  "out_of": 22,
  "page": 1,
  "request_params": { ... },
  "search_time_ms": 1,
  "_meta": {
    "response_time_ms": 12,
    "authenticated_user": null,
    "organization_id": 5,
    "organization_name": "Example Org",
    "auth_type": "api_token",
    "timestamp": "2026-05-04T09:00:00Z"
  }
}

Interactive API Documentation

Use the Swagger UI below to explore and test the API endpoints interactively. Enter your API token to authenticate requests.