AnalyzerGeneratorDictionaryDomainsTools

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

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": "cmudict"
      }
    },
    "scores": {
      "overall": 72,
      "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": "cmudict"
    },
    "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. 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
  }
}

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."
}

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

Error Responses

Error Response Format

Common Error Examples

Missing Phonetic Data (404)

Invalid Parameters (400)

Unauthorized (401)

PhonoPair API
—