Name: Word Tools API - Synonyms, Rhymes, Related Words | QuotaLink
Brand: quotalink
SKU: api-quotalink-word-tools-api
Availability: InStock
Author: API Market

李乐

## Overview

Word Tools API is a set of English lexical lookups behind one base URL: synonyms, rhymes, conceptually related words, adjectives that commonly describe a noun, means-like words with dictionary definitions, and prefix autocomplete. Every endpoint takes a single word and returns a ranked, scored list.

Results are backed by Datamuse, so ranking reflects real corpus usage rather than a static thesaurus. That makes the API useful anywhere you need suggestions ordered by how likely a human is to pick them.

## Features

- **Synonyms**: words with similar meaning, ranked by corpus score.
- **Rhymes**: perfect and near rhymes with syllable counts, useful for lyrics and poetry.
- **Related words**: terms that co-occur with the input, for topic expansion and tagging.
- **Adjectives**: modifiers that commonly describe a given noun.
- **Means-like with definitions**: similar-meaning words returned together with dictionary definitions and part-of-speech tags.
- **Prefix autocomplete**: type-ahead suggestions from a partial word.
- **Syllable counts**: most endpoints return `numSyllables`, handy for meter and readability work.
- **No provider account needed**: your API.market key is the only credential.

## Use Cases

- **Writing and editing tools**: offer synonym and adjective suggestions inline.
- **Songwriting and poetry**: find rhymes filtered by syllable count for a fixed meter.
- **SEO and content planning**: expand a seed keyword into related terms.
- **Search autocomplete**: drive a type-ahead box from `/suggest`.
- **Vocabulary and education apps**: build exercises from definitions and word families.
- **Tagging and classification**: derive candidate tags from related words.
- **Crossword and word-game helpers**: filter candidates by syllables and score.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/quotalink/word-tools-api
```

### Authentication

Pass your API.market key in the `x-api-market-key` header on every request. No other credential is needed.

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Find your key under **Account → API Keys** on api.market. Requests without this header return `400` with `No x-api-market-key or x-magicapi-key defined in headers`.

### Common parameters

Five of the endpoints take the same input. `/suggest` is the exception and is documented separately.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `word` | query | string | Yes | The English word to look up |
| `max` | query | integer | No | Maximum results, default 20 |

The result cap parameter is `max`, not `limit`. A `limit` value is ignored and you will still receive 20 results.

Omitting `word` returns `400` with `{"error":"word parameter required","success":false}`.

### Shared response shape

```json
{
  "word": "happy",
  "type": "synonyms",
  "count": 20,
  "success": true,
  "results": [
    { "word": "halcyon", "score": 61042, "numSyllables": 3 }
  ]
}
```

`results` is ordered by descending `score`. Scores are relative ranking weights from the underlying corpus, not probabilities, so compare them within a single response rather than across queries.

### Endpoints

#### GET /synonyms

Words with a similar meaning to the input.

```bash
curl "https://prod.api.market/api/v1/quotalink/word-tools-api/synonyms?word=happy&max=5" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "word": "happy",
  "type": "synonyms",
  "count": 5,
  "success": true,
  "results": [
    { "word": "halcyon", "score": 61042, "numSyllables": 3 },
    { "word": "content", "score": 57050, "numSyllables": 2 },
    { "word": "bright",  "score": 43054, "numSyllables": 1 }
  ]
}
```

#### GET /rhymes

Words that rhyme with the input. Filter client-side on `numSyllables` when you need to hold a meter.

```bash
curl "https://prod.api.market/api/v1/quotalink/word-tools-api/rhymes?word=light" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "word": "light",
  "type": "rhymes",
  "count": 20,
  "success": true,
  "results": [
    { "word": "insight",  "score": 70044, "numSyllables": 2 },
    { "word": "contrite", "score": 54034, "numSyllables": 2 }
  ]
}
```

#### GET /related

Words that frequently occur alongside the input. This is topical association rather than similarity, so results are broader and sometimes surprising.

```bash
curl "https://prod.api.market/api/v1/quotalink/word-tools-api/related?word=ocean" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "word": "ocean",
  "type": "related",
  "count": 20,
  "success": true,
  "results": [
    { "word": "acidification", "score": 1586, "numSyllables": 6 },
    { "word": "tsunami",       "score": 1437, "numSyllables": 3 }
  ]
}
```

For concrete nouns this works well. For abstract nouns the associations can be loose, so review results before showing them to end users.

#### GET /adjectives

Adjectives commonly used to describe the input noun.

```bash
curl "https://prod.api.market/api/v1/quotalink/word-tools-api/adjectives?word=ocean" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "word": "ocean",
  "type": "adjectives",
  "count": 20,
  "success": true,
  "results": [
    { "word": "open",  "score": 1001, "numSyllables": 2 },
    { "word": "vast",  "score": 999,  "numSyllables": 1 }
  ]
}
```

#### GET /meaning

Returns words that mean roughly the same as the input, each with dictionary definitions and part-of-speech tags.

Read the shape carefully: this endpoint does **not** define the word you send. It returns similar-meaning words and defines *those*. The input word does not appear in `results`.

```bash
curl "https://prod.api.market/api/v1/quotalink/word-tools-api/meaning?word=serendipity" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "word": "serendipity",
  "type": "meaning",
  "count": 20,
  "success": true,
  "results": [
    {
      "word": "chance",
      "score": 29997451,
      "numSyllables": 1,
      "tags": ["n", "results_type:primary_rel"],
      "defs": [
        "n\t(countable) An opportunity or possibility. ",
        "n\t(uncountable) Random occurrence; luck. "
      ]
    }
  ]
}
```

Each entry in `defs` is prefixed with a part-of-speech code and a tab character, for example `n\t` for noun or `v\t` for verb. Split on the tab to separate the code from the definition text. `tags` carries the same part-of-speech codes plus Datamuse result-type markers.

To approximate a definition of the input word, take the highest-scoring result and read its `defs`.

#### GET /suggest

Prefix autocomplete. Note the different parameter name and response field.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `prefix` | query | string | Yes | Partial word to complete |

```bash
curl "https://prod.api.market/api/v1/quotalink/word-tools-api/suggest?prefix=hap" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "prefix": "hap",
  "count": 10,
  "success": true,
  "suggestions": [
    { "word": "hapless",   "score": 57034 },
    { "word": "happy",     "score": 21042 },
    { "word": "haphazard", "score": 14036 }
  ]
}
```

Three differences from the other endpoints: the parameter is `prefix` rather than `word`, the array is `suggestions` rather than `results`, and the count is fixed at 10 (`max` has no effect). Entries carry no `numSyllables`.

Calling it with `word` instead of `prefix` returns `400` with `{"error":"prefix parameter required","success":false}`.

#### GET /health

Service liveness. Takes no parameters and is useful for monitoring.

```bash
curl "https://prod.api.market/api/v1/quotalink/word-tools-api/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{ "service": "word-tools-api", "status": "ok" }
```

## Status Codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Parse the response body |
| `400` | Required parameter or the `x-api-market-key` header is missing | Send `word`, or `prefix` on `/suggest`, and check headers |
| `401` | Invalid or expired API key | Verify the key under Account → API Keys |
| `403` | Your subscription does not cover this endpoint | Check your active plan |
| `429` | Plan quota exhausted or rate limit exceeded | Back off and retry, or upgrade |
| `5xx` | Upstream lexical provider error | Retry with exponential backoff |

## Rate Limits

Both plans allow up to **10 requests per second**. Quotas apply per billing period:

- **FREE**: 100 API units, hard limit. Requests are rejected once the quota is spent.
- **PRO**: 10,000 API units per month, hard limit.

Every endpoint costs one unit per request.

## Error Handling

Errors return JSON with an `error` field and `success: false`:

```json
{ "error": "word parameter required", "success": false }
```

```json
{ "error": "prefix parameter required", "success": false }
```

A word with no matches returns `200` with `count: 0` and an empty array rather than an error, so check `count` before rendering. Retry `5xx` responses with exponential backoff.

## Implementation Guide

### Example Code

```python
import requests

BASE = "https://prod.api.market/api/v1/quotalink/word-tools-api"
HEADERS = {"x-api-market-key": "YOUR_API_MARKET_KEY"}

def rhymes(word, syllables=None, limit=10):
    r = requests.get(f"{BASE}/rhymes", params={"word": word, "max": 50},
                     headers=HEADERS, timeout=15)
    r.raise_for_status()
    results = r.json().get("results", [])
    if syllables is not None:
        results = [x for x in results if x.get("numSyllables") == syllables]
    return [x["word"] for x in results[:limit]]

print(rhymes("light", syllables=2))
```

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/word-tools-api";
const headers = { "x-api-market-key": process.env.API_MARKET_KEY };

async function autocomplete(prefix) {
  if (prefix.length < 2) return [];
  const res = await fetch(
    `${BASE}/suggest?prefix=${encodeURIComponent(prefix)}`,
    { headers }
  );
  if (!res.ok) throw new Error(`Suggest failed: ${res.status}`);
  const { suggestions = [] } = await res.json();
  return suggestions.map((s) => s.word);
}

console.log(await autocomplete("hap"));
```

### Performance Optimization

- Cache aggressively by endpoint and word. The English language does not change between requests, so results are effectively permanent and a long TTL removes almost all repeat traffic.
- Debounce autocomplete input by 250 to 300 milliseconds and require at least two characters. Without that, a single typed word costs one call per keystroke.
- Request `max=50` once and filter client-side rather than issuing several narrower calls. Filtering by syllable count costs nothing locally.
- Stay within 10 requests per second when processing a word list, and queue the work instead of firing it all in parallel.

## FAQ

**Do I need an account with QuotaLink or Datamuse to use this API?**

No. Your API.market key is the only credential required.

**Does `/meaning` define the word I send?**

No. It returns similar-meaning words along with their definitions, and your input word is not included in the results. For an approximate definition, read `defs` on the top-scoring result.

**Why does `limit` not work?**

The result cap parameter is `max`. On `/suggest` neither applies, since it always returns 10 suggestions.

**Why is `/suggest` different from the other endpoints?**

It takes `prefix` instead of `word` and returns a `suggestions` array instead of `results`, because it completes a partial word rather than looking up a whole one.

**What does `score` mean?**

A relative ranking weight from the underlying corpus. Use it to order results within one response; do not compare scores between different queries.

**What is the `n\t` prefix in definitions?**

A part-of-speech code followed by a tab: `n` for noun, `v` for verb, `adj` for adjective. Split on the tab character.

**Which languages are supported?**

English only.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


English word tools: synonyms, rhymes, related words, adjectives, auto-complete. Free API for writers and developers.