AnalyzerGeneratorCompareDictionaryDomainsTools

PhonoPair API
—

Complete guide to the PhonoPair API for programmatic word pair analysis

Access our RESTful API to integrate phonetic analysis into your applications. Generate word pairs, analyze phonetic compatibility, and explore our linguistic dictionary.

Quick Start

Get started with the PhonoPair API in minutes:

Create an API token from your dashboard
Include the token in your request headers
Start making API calls to analyze word pairs

Rate Limits

Free: 50 requests/day

Pro: 500 requests/day

Enterprise: Unlimited

View pricing details →

Authentication

The PhonoPair API uses Bearer token authentication. Include your API token in the Authorization header of all requests.

Getting Started: Create an API token from your dashboard to begin making API requests.

Authentication Header

HTTP

Copy

Authorization: Bearer wp_your_token_here

Code Examples

bash

Copy

curl -X GET "https://phonopair.com/api/word-pairs?word1=hello&word2=world" \
  -H "Authorization: Bearer wp_your_token_here"

Rate Limits

API requests are limited based on your subscription tier:

Tier	Requests/Day	Max Tokens	Price
FREE	50	1	$0/month
PRO	500	3	$29/month
ENTERPRISE	Unlimited	10	$99/month

When you exceed your rate limit, the API returns a 429 status code with an error message indicating when you can make requests again.

API Endpoints

Word Pair Analysis

Example scores are illustrative. scores.overall (= blendedScore) is 40% word quality + 60% compatibility; scores.compatibilityScore is the pair compatibility after the soft ceiling (always below 100). Each word's source names where its pronunciation came from: custom (curated brand words), cmu (curated CMU subset), names (reviewed first-name table), cmudict (full CMU Pronouncing Dictionary), compound (hyphenated or multi-word, resolved per part), merriamWebster, wordsApi, or synthetic_g2p (estimated from spelling).

GET

/api/word-pairs

FREE

Comprehensive word pair analysis using Three-Pillar Architecture: Phonetic Analysis, Language Structure, and Semantic & Cultural Patterns. Returns detailed scoring with component breakdowns, bonus factors, and order comparison.

Parameters

Name	Type	Required	Default	Description
word1	string	Yes	-	First word to analyze
word2	string	Yes	-	Second word to analyze
format	string	No	full	Response format: "full", "compact", or "scores-only"
skipCustom	boolean	No	false	Skip custom dictionary sources
tryAllSources	boolean	No	false	Try all available phonetic data sources
allowSynthetic	boolean	No	false	Allow synthetic phonetic generation for non-dictionary words
context	string	No	brandability	Analysis context (future use)

Example Request

bash

Copy

curl -X GET "https://phonopair.com/api/word-pairs?word1=hello&word2=world" \\\n  -H "Authorization: Bearer wp_your_token_here"

Additional Examples

Compact Format (Less Data)

bash

Copy

curl -X GET "https://phonopair.com/api/word-pairs?word1=hello&word2=world&format=compact" \
  -H "Authorization: Bearer wp_your_token_here"

Scores Only (Minimal Response)

bash

Copy

curl -X GET "https://phonopair.com/api/word-pairs?word1=hello&word2=world&format=scores-only" \
  -H "Authorization: Bearer wp_your_token_here"

With Synthetic Phonetics (For Non-Dictionary Words)

bash

Copy

curl -X GET "https://phonopair.com/api/word-pairs?word1=techify&word2=sparkle&allowSynthetic=true" \
  -H "Authorization: Bearer wp_your_token_here"

Skip External Sources (Faster)

bash

Copy

curl -X GET "https://phonopair.com/api/word-pairs?word1=hello&world=world&skipCustom=true" \
  -H "Authorization: Bearer wp_your_token_here"

Example Response

JSON

Copy

{
  "success": true,
  "type": "word-pair-analysis",
  "data": {
    "words": {
      "word1": "hello",
      "word2": "world"
    },
    "phonemes": {
      "word1": {
        "phonemes": [
          "HH",
          "AH",
          "L",
          "OW"
        ],
        "source": "cmudict"
      },
      "word2": {
        "phonemes": [
          "W",
          "ER",
          "L",
          "D"
        ],
        "source": "cmu"
      }
    },
    "scores": {
      "overall": 72,
      "blendedScore": 72,
      "compatibilityScore": 70,
      "baseScore": 55,
      "adjustedBaseScore": 60,
      "bonusScore": 12,
      "components": {
        "vowelShape": 60,
        "assonance": 55,
        "consonantPlacement": 70,
        "consonance": 65,
        "syllableRhythm": 58,
        "mouthTransition": 62,
        "alliteration": 50
      }
    },
    "pillars": {
      "pillar1": {
        "name": "Phonetic Analysis",
        "score": 55,
        "explanation": "Moderate phonetic compatibility...",
        "components": {},
        "phoneticPatterns": {}
      },
      "pillar2": {
        "name": "Language Structure",
        "score": 5,
        "explanation": "Positive linguistic adjustments...",
        "components": {},
        "adjustments": {}
      },
      "pillar3": {
        "name": "Semantic & Cultural Patterns",
        "score": 12,
        "explanation": "Detected cultural metonymy...",
        "semanticFactors": {
          "positive": [],
          "negative": []
        },
        "components": {}
      }
    }
  },
  "metadata": {
    "format": "full",
    "skipCustomDict": false,
    "tryAllSources": false,
    "sources": {
      "word1Source": "cmudict",
      "word2Source": "cmu"
    },
    "timestamp": "2025-01-08T12:00:00.000Z"
  }
}

GET

/api/word-pairs (Single Word)

FREE

Get phonetic data for a single word. Returns phonemes, syllable count, stress pattern, and source information.

Parameters

Name	Type	Required	Default	Description
word	string	Yes	-	Word to analyze
skipCustom	boolean	No	false	Skip custom dictionary sources
tryAllSources	boolean	No	false	Try all available phonetic data sources

Example Request

bash

Copy

curl -X GET "https://phonopair.com/api/word-pairs?word=hello" \\\n  -H "Authorization: Bearer wp_your_token_here"

Example Response

JSON

Copy

{
  "success": true,
  "type": "single-word",
  "data": {
    "word": "hello",
    "phonemes": [
      "HH",
      "AH",
      "L",
      "OW"
    ],
    "source": "cmudict",
    "syllables": 2,
    "stressPattern": "N/A"
  },
  "metadata": {
    "skipCustomDict": false,
    "tryAllSources": false,
    "timestamp": "2025-01-08T12:00:00.000Z"
  }
}

POST

/api/word-pairs/batch

PRO

Analyze multiple word pairs in a single request. Returns an array of analysis results. Limited to 50 pairs per request and 100 pairs per minute per IP (429 with Retry-After beyond that). Supports all format options.

Parameters

Name	Type	Required	Default	Description
pairs	array	Yes	-	Array of word pair objects with word1 and word2 properties
options.format	string	No	compact	Response format for all pairs: "full", "compact", or "scores-only"
options.skipCustom	boolean	No	false	Skip custom dictionary sources for all pairs
options.tryAllSources	boolean	No	false	Try all available phonetic data sources for all pairs

Example Request

bash

Copy

curl -X POST "https://phonopair.com/api/word-pairs/batch" \
  -H "Authorization: Bearer wp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "pairs": [
      {"word1": "hello", "word2": "world"},
      {"word1": "quick", "word2": "silver"}
    ],
    "options": {
      "format": "compact"
    }
  }'

Additional Examples

Batch with Full Format

bash

Copy

curl -X POST "https://phonopair.com/api/word-pairs/batch" \
  -H "Authorization: Bearer wp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "pairs": [
      {"word1": "tech", "word2": "spark"},
      {"word1": "blue", "word2": "sky"}
    ],
    "options": {
      "format": "full",
      "tryAllSources": true
    }
  }'

Batch with Scores Only

bash

Copy

curl -X POST "https://phonopair.com/api/word-pairs/batch" \
  -H "Authorization: Bearer wp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "pairs": [
      {"word1": "fast", "word2": "lane"},
      {"word1": "smart", "word2": "hub"}
    ],
    "options": {
      "format": "scores-only"
    }
  }'

Example Response

JSON

Copy

{
  "success": true,
  "type": "batch-analysis",
  "data": {
    "successful": [
      {
        "word1": "hello",
        "word2": "world",
        "success": true,
        "data": {
          "scores": {
            "overall": 72
          }
        }
      },
      {
        "word1": "quick",
        "word2": "silver",
        "success": true,
        "data": {
          "scores": {
            "overall": 85
          }
        }
      }
    ],
    "failed": [],
    "stats": {
      "total": 2,
      "successful": 2,
      "failed": 0
    }
  },
  "metadata": {
    "format": "compact",
    "options": {
      "skipCustom": false,
      "tryAllSources": false
    },
    "timestamp": "2025-01-08T12:00:00.000Z"
  }
}

Dictionary & Phonetic Exploration

GET

/api/dictionary

FREE

Search the phonetic dictionary with advanced filtering by query, category, and sound pattern. Returns enriched results with phonetic analysis.

Parameters

Name	Type	Required	Default	Description
query	string	No	""	Search query (searches word, phonetic, and category)
category	string	No	any	Filter by category: "any", "music", "tech", "nature", "power", "color", "abstract", "sound", "rhythm", "speed", "style", "business"
pattern	string	No	""	Filter by sound pattern: "smooth", "hard", "soft", "rhythmic", "melodic", "staccato"
limit	number	No	50	Maximum number of results to return (1-100)

Example Request

bash

Copy

curl -X GET "https://phonopair.com/api/dictionary?query=flow&category=nature&pattern=smooth" \\\n  -H "Authorization: Bearer wp_your_token_here"

Additional Examples

Search by Category Only

bash

Copy

curl -X GET "https://phonopair.com/api/dictionary?category=tech&limit=20" \
  -H "Authorization: Bearer wp_your_token_here"

Search by Pattern Only

bash

Copy

curl -X GET "https://phonopair.com/api/dictionary?pattern=melodic&limit=30" \
  -H "Authorization: Bearer wp_your_token_here"

General Text Search

bash

Copy

curl -X GET "https://phonopair.com/api/dictionary?query=melody" \
  -H "Authorization: Bearer wp_your_token_here"

Example Response

JSON

Copy

{
  "query": "flow",
  "category": "nature",
  "pattern": "smooth",
  "totalResults": 3,
  "results": [
    {
      "word": "flow",
      "phonetic": "/floʊ/",
      "syllables": 1,
      "stress": "1",
      "vowels": "oʊ",
      "category": "nature",
      "patterns": [
        "smooth",
        "melodic"
      ],
      "phonemes": [
        "F",
        "L",
        "OW"
      ],
      "source": "dictionary"
    },
    {
      "word": "wave",
      "phonetic": "/weɪv/",
      "syllables": 1,
      "stress": "1",
      "vowels": "eɪ",
      "category": "nature",
      "patterns": [
        "smooth",
        "melodic"
      ],
      "phonemes": [
        "W",
        "EY",
        "V"
      ],
      "source": "dictionary"
    }
  ]
}

GET

/api/phonetics

FREE

Get phonetic data for a single word or analyze compatibility between two words. Returns detailed phonetic breakdown with component scores.

Parameters

Name	Type	Required	Default	Description
word	string	No	-	Single word to analyze (mutually exclusive with word1/word2)
word1	string	No	-	First word for pair analysis (requires word2)
word2	string	No	-	Second word for pair analysis (requires word1)
skipCustom	boolean	No	false	Skip custom dictionary sources
tryAllSources	boolean	No	false	Try all available phonetic data sources

Example Request

bash

Copy

curl -X GET "https://phonopair.com/api/phonetics?word1=hello&word2=world" \\\n  -H "Authorization: Bearer wp_your_token_here"

Additional Examples

Single Word Phonetic Data

bash

Copy

curl -X GET "https://phonopair.com/api/phonetics?word=hello" \
  -H "Authorization: Bearer wp_your_token_here"

Pair Analysis with All Sources

bash

Copy

curl -X GET "https://phonopair.com/api/phonetics?word1=tech&word2=spark&tryAllSources=true" \
  -H "Authorization: Bearer wp_your_token_here"

Example Response

JSON

Copy

{
  "word1": "hello",
  "word2": "world",
  "phonemeData": {
    "word1": {
      "phonemes": [
        "HH",
        "AH",
        "L",
        "OW"
      ],
      "found": true
    },
    "word2": {
      "phonemes": [
        "W",
        "ER",
        "L",
        "D"
      ],
      "found": true
    }
  },
  "scores": {
    "baseScore": 55,
    "bonusScore": 12,
    "overall": 67,
    "assonance": 55,
    "consonance": 65,
    "rhythm": 58,
    "vowelShape": 60,
    "consonantPlacement": 70
  },
  "orderComparison": {
    "normalOrder": "hello world",
    "normalOrderScore": 67,
    "reversedOrder": "world hello",
    "reversedOrderScore": 65,
    "preferReversed": false,
    "scoreDifference": 2
  },
  "explanation": "Phonetic analysis explanation...",
  "bonusFactors": {
    "positiveFactors": [],
    "negativeFactors": []
  },
  "confidence": 0.85,
  "sources": {
    "unified": true,
    "skipExternal": false,
    "tryAllSources": false
  }
}

Name Finder

GET

/api/name-finder

FREE

Rank 6,671 US first names (Social Security Administration top-1000 lists, 1900-2024) by how well they flow with a last name, find sound-alikes for a name you like, or get compact suggestions (view=suggest). Public, no token needed. Scores use the same pair-scoring core as /api/word-pairs in offline mode (no ConceptNet relationship or Wikipedia lookups between the two names; each name's own semantic signals are still used), so a few full names can differ by a few points from the analyzer. Non-canonical query strings (other parameter order, casing or unknown parameters) get a 308 redirect to the canonical URL, so follow redirects. Errors use { success: false, error: <code>, message }: 400 invalid_surname / invalid_like / invalid_view / missing_like, 404 unpronounceable_surname / not_in_list (explain view), 422 unpronounceable_like, 429 rate_limited (12 uncached surnames per minute per client; honour Retry-After), 500 internal_error.

Parameters

Name	Type	Required	Default	Description
surname	string	Yes	-	Last name: letters, spaces, hyphens or apostrophes, 1-40 characters
like	string	No	-	A first name you like. Adds sound-alikes (full view); required for view=suggest and view=explain
view	string	No	full	Omit for the full ranking, "suggest" for compact suggestions, or "explain" for one listed name's score breakdown (40% quality + 60% compatibility, sound match, where the names meet, sound repeats)
gender	string	No	any	Suggest view: "girl" or "boy" (defaults to the liked name's dominant usage)
limit	number	No	6	Suggest view: number of suggestions (1-12)

Example Request

bash

Copy

curl -L "https://phonopair.com/api/name-finder?surname=keaveney&like=rose"

Additional Examples

Suggestions for the analyzer (view=suggest)

bash

Copy

curl -L "https://phonopair.com/api/name-finder?surname=keaveney&like=lila&view=suggest&gender=girl&limit=3"

Suggest view response (illustrative)

JSON

Copy

{
  "success": true,
  "data": {
    "surname": "keaveney",
    "basis": "first+last",
    "name": "lila",
    "score": 72,
    "approximate": false,
    "gender": "girl",
    "suggestions": [
      {
        "name": "Layla",
        "score": 77,
        "delta": 5
      },
      {
        "name": "Lola",
        "score": 75,
        "delta": 3
      }
    ]
  }
}

Error response

JSON

Copy

{
  "success": false,
  "error": "missing_like",
  "message": "Add a first name (like=) to get suggestions."
}

Example Response

JSON

Copy

{
  "success": true,
  "data": {
    "surname": "keaveney",
    "phonemes": [
      "K",
      "IY",
      "V",
      "AH",
      "N",
      "IY"
    ],
    "source": "cmudict",
    "approximate": false,
    "corpusVersion": "3f9c1a2b7d4e",
    "scores": [
      71.4,
      68.2,
      74.9,
      "... one score (1 decimal) per corpus row, in corpus order"
    ],
    "like": {
      "found": true,
      "name": "rose",
      "phonemes": [
        "R",
        "OW",
        "Z"
      ],
      "source": "corpus",
      "approximate": false,
      "score": 76.3,
      "index": 5120,
      "gender": "girl",
      "features": {
        "stress": "1",
        "ending": "h",
        "feel": "s"
      },
      "neighbors": [
        [
          5125,
          0.12
        ],
        [
          4810,
          0.31
        ],
        "... up to 300 [corpus index, sound distance] pairs"
      ]
    }
  }
}

GET

/api/name-finder/corpus

FREE

The static Name Finder corpus: every name with its pronunciation, stress, sound features, sound-map position, Wikipedia page flag and SSA popularity stats. Request it as /api/name-finder/corpus?v=<corpusVersion> using the corpusVersion from /api/name-finder, and discard a body whose v does not match. Rows line up with the scores array. girl/boy are 0 when the name never reached that list, otherwise stats in statFields order (rank 0 = not in that year's top 1000).

Parameters

Name	Type	Required	Default	Description
v	string	No	-	Corpus version from /api/name-finder (cache key; the body carries the same v)

Example Request

bash

Copy

curl "https://phonopair.com/api/name-finder/corpus?v=3f9c1a2b7d4e"

Example Response

JSON

Copy

{
  "v": "3f9c1a2b7d4e",
  "source": {
    "ssa": "aruljohn/popular-baby-names@91bb24b84af1",
    "years": [
      1900,
      2024
    ]
  },
  "fields": [
    "name",
    "phonemes",
    "stress",
    "ending",
    "feel",
    "wiki",
    "x",
    "y",
    "girl",
    "boy"
  ],
  "statFields": [
    "rank2024",
    "bestRank",
    "peakYear",
    "yearsInTop1000",
    "firstYear",
    "rank2014"
  ],
  "rows": [
    [
      "Aaron",
      "EH R AH N",
      "10",
      "s",
      "s",
      0,
      297,
      649,
      [
        0,
        871,
        1976,
        9,
        1975,
        0
      ],
      [
        79,
        28,
        1994,
        125,
        1900,
        50
      ]
    ]
  ]
}

Error Responses

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Description
200	Success - Request completed successfully
400	Bad Request - Invalid parameters or request format
401	Unauthorized - Invalid or missing API token
403	Forbidden - Feature not available in your subscription tier
404	Not Found - Phonetic data not found for the requested word(s)
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Unexpected server error

Error Response Format

JSON

Copy

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "You have exceeded your daily API limit of 50 requests. Upgrade your subscription for more requests.",
  "upgrade": true
}

Common Error Examples

Missing Phonetic Data (404)

JSON

Copy

{
  "success": false,
  "error": "Missing phonetic data",
  "data": {
    "word1": "hello",
    "word2": "xyzabc",
    "word1Found": true,
    "word2Found": false,
    "word1IsReal": true,
    "word2IsReal": false
  },
  "message": "Could not find phonetic data for xyzabc",
  "suggestion": "Try adding allowSynthetic=true to use approximate phonetics for non-dictionary words"
}

Invalid Parameters (400)

JSON

Copy

{
  "success": false,
  "error": "Invalid request parameters",
  "message": "Provide either \"word\" for single word analysis, or both \"word1\" and \"word2\" for pair analysis",
  "supportedFormats": [
    "full",
    "compact",
    "scores-only"
  ]
}

Unauthorized (401)

JSON

Copy

{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid or missing API token. Please include a valid Bearer token in the Authorization header."
}

Client libraries

Don't want to call the REST API directly? Use our official npm packages.

@phonopair/sdk →@phonopair/phonetic-pair →

Rate limits and API access

The free tier allows 50 requests/day. For higher limits, see pricing.

See pricing →

PhonoPair API—

Quick Start

Rate Limits

Authentication

Authentication Header

Code Examples

Rate Limits

API Endpoints

Word Pair Analysis

Parameters

Example Request

Additional Examples

Compact Format (Less Data)

Scores Only (Minimal Response)

With Synthetic Phonetics (For Non-Dictionary Words)

Skip External Sources (Faster)

Example Response

Parameters

Example Request

Example Response

Parameters

Example Request

Additional Examples

Batch with Full Format

Batch with Scores Only

Example Response

Dictionary & Phonetic Exploration

Parameters

Example Request

Additional Examples

Search by Category Only

Search by Pattern Only

General Text Search

Example Response

Parameters

Example Request

Additional Examples

Single Word Phonetic Data

Pair Analysis with All Sources

Example Response

Name Finder

Parameters

Example Request

Additional Examples

Suggestions for the analyzer (view=suggest)

Suggest view response (illustrative)

Error response

Example Response

Parameters

Example Request

Example Response

Error Responses

Error Response Format

Common Error Examples

Missing Phonetic Data (404)

Invalid Parameters (400)

Unauthorized (401)

Client libraries

Rate limits and API access

PhonoPair API
—