Code Examples

Get started quickly with ready-to-use code examples. All examples are copy-paste ready and tested.

Getting Started

All API requests require authentication using an API key. You can get your API key from the API Dashboard. Include it in the x-api-key header with each request.

Common Use Cases

Get Today's Namedays for a Country

Fetch the namedays being celebrated today in a specific country.

curl -X GET "https://name.birrday.com/api/namedays?country=SE&date=$(date +%Y-%m-%d)" \
  -H "x-api-key: YOUR_API_KEY"

Get Namedays for a Specific Date

Retrieve nameday celebrations for any date in the past or future.

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

Get All Namedays for a Month

Fetch all nameday celebrations for an entire month.

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

Search for a Name

Find when and where a specific name is celebrated.

curl -X GET "https://name.birrday.com/api/search?q=Maria" \
  -H "x-api-key: YOUR_API_KEY"

Handle Pagination

Navigate through large result sets using pagination.

# First page
curl -X GET "https://name.birrday.com/api/search?q=John&page=1&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

# Next page
curl -X GET "https://name.birrday.com/api/search?q=John&page=2&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

Error Handling

Properly handle API errors and rate limits.

# Check response status
curl -w "\nHTTP Status: %{http_code}\n" \
  -X GET "https://name.birrday.com/api/namedays?country=INVALID" \
  -H "x-api-key: YOUR_API_KEY"

Best Practices

Security

•Never expose API keys: Always use environment variables or server-side proxies
•Backend proxy: For browser apps, proxy requests through your backend to hide the API key
•HTTPS only: Always use HTTPS when making API requests

Performance

•Cache responses: Nameday data is static and can be cached for long periods
•Handle rate limits: Check Retry-After headers and implement exponential backoff
•Use pagination: Don't fetch all results at once for large datasets

Error Handling

•Always check status codes: Handle 4xx and 5xx errors appropriately
•Implement retries: Use exponential backoff for transient failures
•Set timeouts: Don't wait indefinitely for responses

Framework Examples

React Hook

import { useState, useEffect } from 'react';

function useNamedays(country: string, date?: string) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    async function fetchNamedays() {
      try {
        setLoading(true);
        const params = new URLSearchParams({ country });
        if (date) params.append('date', date);

        const response = await fetch(
          `/api/namedays?${params}` // Use your backend proxy
        );

        if (!response.ok) {
          throw new Error('Failed to fetch namedays');
        }

        const result = await response.json();
        setData(result);
      } catch (err) {
        setError(err instanceof Error ? err : new Error('Unknown error'));
      } finally {
        setLoading(false);
      }
    }

    fetchNamedays();
  }, [country, date]);

  return { data, loading, error };
}

// Usage in component
function NamedayDisplay({ country }: { country: string }) {
  const { data, loading, error } = useNamedays(country);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!data) return null;

  return (
    <div>
      <h2>Namedays in {country}</h2>
      {data.namedays.map((celebration, idx) => (
        <div key={idx}>
          <h3>{celebration.tradition}</h3>
          <p>{celebration.names.join(', ')}</p>
        </div>
      ))}
    </div>
  );
}

Next.js Server Component

// app/namedays/[country]/page.tsx
import { notFound } from 'next/navigation';

async function getNamedays(country: string) {
  const response = await fetch(
    `https://name.birrday.com/api/namedays?country=${country}`,
    {
      headers: {
        'x-api-key': process.env.NAMEDAY_API_KEY!,
      },
      next: {
        revalidate: 86400, // Cache for 24 hours
      },
    }
  );

  if (!response.ok) {
    throw new Error('Failed to fetch namedays');
  }

  return response.json();
}

export default async function NamedaysPage({
  params,
}: {
  params: { country: string };
}) {
  try {
    const data = await getNamedays(params.country);

    return (
      <div>
        <h1>Namedays in {params.country}</h1>
        {data.namedays.map((celebration, idx) => (
          <div key={idx}>
            <h2>{celebration.tradition}</h2>
            <p>{celebration.names.join(', ')}</p>
          </div>
        ))}
      </div>
    );
  } catch {
    notFound();
  }
}

Need More Examples?

Looking for examples in other languages or frameworks? Let us know what you need!

Request Examples

Get Your API Key