API Reference

v1.0 · Chavacano API

The Chavacano API lets you translate English words into Chavacano — the only Spanish-based creole language in Asia, spoken in Ternate, Philippines.

Introduction

All API endpoints are served from http://localhost:3000 when running locally. Every endpoint except /api/generate-key requires authentication.

Authentication

Pass your API key in the x-api-key request header on every call.

Header
x-api-key: chav_your_key_here
💡 Get a free API key from the Dashboard.

Rate Limiting

Each API key is limited to 60 requests per minute. If you exceed this, you'll receive a 429 response with a retryAfter field (in seconds).

Endpoints

Translate a Word

GET /api/translate Translate an English word to Chavacano
Parameter Type Required Description
word string Yes The English word to translate
Example Request
GET /api/translate?word=hello
x-api-key: chav_abc123
Example Response
{
  "english":   "hello",
  "chavacano": "hola",
  "category":  "greeting",
  "example":   "Hola, como ta ustedes?"
}
GET /api/search Search English or Chavacano words
Parameter Type Required Description
q string Yes Search query (searches both English and Chavacano)
Example
GET /api/search?q=amor

Random Word

GET /api/random Get a random word pair

No parameters required. Returns a random English–Chavacano pair.

Browse Dictionary

GET /api/dictionary Browse all words with pagination
Parameter Type Required Description
category string No Filter by category (e.g. greeting, action, people)
page number No Page number (default: 1)
limit number No Results per page (default: 20)

Categories

GET /api/categories List all categories and word counts

Returns all available categories and how many words are in each.

Usage Stats

GET /api/stats Get usage stats for your key

Returns request count, rate limit status, and last used timestamp.

Generate Key

POST /api/generate-key Create a new API key

No body or authentication required. Returns a new API key.

Error Codes

400Bad RequestMissing required query parameter
401UnauthorizedMissing or invalid x-api-key header
404Not FoundWord not in the dictionary
429Rate LimitedExceeded 60 requests per minute

Code Examples

JavaScript (fetch)

// Translate "love" to Chavacano
const response = await fetch('/api/translate?word=love', {
  headers: { 'x-api-key': 'chav_your_key_here' }
});
const data = await response.json();
console.log(data.chavacano); // "amor"

Python

import requests

res = requests.get(
    'http://localhost:3000/api/translate',
    params={'word': 'water'},
    headers={'x-api-key': 'chav_your_key_here'}
)
print(res.json()['chavacano'])  # "agua"

curl

curl -H "x-api-key: chav_your_key_here" \
  "http://localhost:3000/api/translate?word=friend"
✓ Tip: All responses are JSON. Always check the HTTP status code before reading the body.