Ordinal Number API: The Complete Guide to 1st, 2nd, 3rd Conversion

Need to display rankings, positions, or dates with proper ordinal suffixes? This guide covers everything you need to know about converting numbers to ordinals via API, including locale-specific rules and implementation examples in multiple languages.

What are Ordinal Numbers?

Ordinal numbers indicate position or order in a sequence. Unlike cardinal numbers (1, 2, 3), ordinals (1st, 2nd, 3rd) express ranking, dates, or sequential positions.

For example, "She finished 1st in the race" uses an ordinal, while "She has 1 medal" uses a cardinal number.

English Ordinal Rules

English ordinals follow specific suffix rules:

Standard Suffixes

1st, 2nd, 3rd, then 4th through 20th use "th". The pattern repeats: 21st, 22nd, 23rd, 24th...

Teen Exception

Numbers 11, 12, 13 always use "th" (11th, 12th, 13th), not "st", "nd", "rd" like 1, 2, 3.

Algorithm

Check the last two digits: if 11-13, use "th". Otherwise, check last digit: 1="st", 2="nd", 3="rd", else "th".

Using the Ordinal Number API

TinyFn provides a simple endpoint to convert numbers to ordinals:

GET https://api.tinyfn.io/v1/format/ordinal?number=42
Headers: X-API-Key: your-api-key

{
  "number": 42,
  "ordinal": "42nd",
  "suffix": "nd",
  "locale": "en"
}

Parameters

Code Examples

JavaScript / Node.js

// Convert number to ordinal
const response = await fetch(
  'https://api.tinyfn.io/v1/format/ordinal?number=42',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { ordinal } = await response.json();
console.log(ordinal); // 42nd

// Get multiple ordinals
const numbers = [1, 2, 3, 11, 12, 13, 21, 22, 23];
const ordinals = await Promise.all(
  numbers.map(async n => {
    const res = await fetch(
      `https://api.tinyfn.io/v1/format/ordinal?number=${n}`,
      { headers: { 'X-API-Key': 'your-api-key' } }
    );
    return (await res.json()).ordinal;
  })
);
console.log(ordinals); // ['1st', '2nd', '3rd', '11th', '12th', '13th', '21st', '22nd', '23rd']

Python

import requests

# Convert number to ordinal
response = requests.get(
    'https://api.tinyfn.io/v1/format/ordinal',
    params={'number': 42},
    headers={'X-API-Key': 'your-api-key'}
)
print(response.json()['ordinal'])  # 42nd

# Test edge cases
for n in [1, 2, 3, 11, 12, 13, 21, 22, 23, 100, 101, 111]:
    response = requests.get(
        'https://api.tinyfn.io/v1/format/ordinal',
        params={'number': n},
        headers={'X-API-Key': 'your-api-key'}
    )
    print(f"{n} -> {response.json()['ordinal']}")

cURL

# Get ordinal for 42
curl "https://api.tinyfn.io/v1/format/ordinal?number=42" \
  -H "X-API-Key: your-api-key"

# Get ordinal with long format
curl "https://api.tinyfn.io/v1/format/ordinal?number=3&format=long" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Leaderboards: Display rankings (1st place, 2nd place)
• Dates: Format days of month (January 1st, March 23rd)
• Anniversaries: Show milestone years (25th anniversary)
• Sports: Display finishing positions in races
• Education: Grade levels (3rd grade, 12th grade)

Best Practices

1. Handle negatives and zero: Decide how to handle edge cases (0th? -1st?)
2. Consider superscript: Use 1^st for better typography
3. Internationalize: Different languages have different ordinal rules
4. Cache common values: 1st-31st are commonly used for dates

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-format": {
      "url": "https://api.tinyfn.io/mcp/format/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all formatting tools available via MCP in our Formatting MCP Tools for AI Agents guide.