# Emoji Score

> Score any emoji instantly. Browse 3,900+ Unicode emoji by version, explore trends, and submit new proposals backed by research.
> Part of the PlatPhorm News network (*.platphormnews.com).
> Live at: https://emoji.platphormnews.com

## Overview

Emoji Score is a Next.js web application and REST API that provides:
- **Scoring** — Evaluate any emoji character's popularity, versatility, and platform support (score 0-100, tier classification).
- **Proposal Scoring** — Submit a new emoji concept and get evidence-based feedback against the 7 Unicode Consortium selection criteria.
- **Inventory Search** — Search 3,900+ fully-qualified Unicode 17.0 emoji by name, keyword, group, or code point.
- **Timeline** — Browse emoji additions by year from 2010 to present.
- **MCP Integration** — Discoverable by AI agents via the PlatPhorm MCP Registry at https://mcp.platphormnews.com/api/mcp.

## API Reference

Base URL: https://emoji.platphormnews.com

### Health Check
GET /api/v1/health
Returns server status, uptime, version, and network info.
Response: { "status": "ok", "time": "ISO8601", "uptime_seconds": N, "version": "17.0", "name": "Emoji Score", "network": "platphormnews.com", "url": "https://emoji.platphormnews.com", "mcp_registry": "https://mcp.platphormnews.com/api/mcp", "emoji_count": 3900 }

### Score an Emoji
GET /api/emoji/score?emoji={emoji}
Scores a Unicode emoji character for popularity, versatility, and platform support.
Parameters: emoji (required) — URL-encoded emoji character.
Response: { "emoji": "😂", "unicodeName": "face with tears of joy", "overall": 95, "tier": "Highly Popular", "breakdown": { "category": { "score": 38, "max": 40 }, "versatility": { "score": 25, "max": 25 }, "complexity": { "score": 20, "max": 20 }, "specificity": { "score": 15, "max": 15 } } }

### Score a Proposal
POST /api/v1/emoji/score
Body: { "type": "score_request", "created_at": "ISO8601", "proposal": { "concept_name": "string", "short_name": "string", "keywords": ["string"], "usage_examples": ["string"], "visual_spec": "string", "exclusions": "string" } }
Evaluates an emoji concept against seven weighted criteria. Returns viability score and recommendations. Stateless.
Response: { "type": "score_response", "score_0_100": N, "p_accept": 0.0-1.0, "breakdown": { "demand": 0-1, "universality": 0-1, "semantic_gap": 0-1, "longevity": 0-1, "visual_distinctiveness": 0-1, "neutrality": 0-1, "completeness": 0-1 }, "gates": [...], "nearest_existing_emoji_ranked": [...], "recommendations": [...] }

### Search Emoji
GET /api/emoji/local-search?q={query}&group={group}&limit={limit}
Full-text search of the local Unicode database. Returns ranked results.
Parameters: q (optional), group (optional), limit (optional, default 50, max 200).
Response: { "emojis": [{ "character": "🔥", "name": "fire", "codePoints": "1F525", "group": "Travel & Places", "subGroup": "sky & weather", "version": "6.0", "keywords": ["fire", "flame", "hot"] }] }

### Suggest Emoji
GET /api/emoji/suggest?q={partial}&limit={limit}
Typeahead suggestions. Returns up to 8 matching emoji. Designed for autocomplete UIs.
Parameters: q (required), limit (optional, default 8, max 20).
Response: [{ "character": "🔥", "name": "fire", "group": "Travel & Places" }]

### Full Dataset
GET /api/emoji/all
Returns all 3,900+ Unicode 17.0 emoji in compact JSON format for client-side caching.
Response: { "version": "17.0", "count": 3900, "emojis": [{ "c": "😀", "n": "grinning face", "cp": "1F600", "g": "Smileys & Emotion", "sg": "face-smiling", "v": "6.1", "z": 0, "cpc": 1 }] }

### Timeline
GET /api/emoji/timeline
Returns emoji additions grouped by year with Unicode version labels.
Response: { "totalEmoji": 3900, "version": "17.0", "timeline": [{ "year": 2010, "versions": ["1.0"], "count": 722, "samples": ["😀", "❤️"] }] }

### Recent Emoji
GET /api/emoji/recent
Returns emoji added in Unicode 15.1 (2023), 16.0 (2024) and 17.0 (2025).
Response: { "totalRecent": N, "grouped": { "17.0": [...], "16.0": [...], "15.1": [...] } }

### Categories
GET /api/emoji/categories
Returns all emoji categories with counts and sample characters.
Response: [{ "slug": "smileys-emotion", "name": "Smileys & Emotion", "count": 184, "sample": ["😀", "😃", "😄", "😁", "😆"] }]

### Find Emoji by Description
GET /api/v1/emoji/from-description?description={text}&limit={limit}&include_score={boolean}
Find emoji that match a natural-language description. Designed for MCP tool ingestion.
Parameters: description (required), limit (optional, default 10, max 50), include_score (optional, default false).
Response: { "description": "happy face", "count": 10, "emojis": [{ "character": "😊", "name": "smiling face with smiling eyes", "group": "Smileys & Emotion", "keywords": [...], "matchedTerms": ["happy", "face"] }] }

### Inventory Search
GET /api/v1/datasets/emoji/inventory/search?q={query}&limit={limit}&include_external={boolean}
Search the canonical Unicode inventory with CLDR names and keywords.
Parameters: q (required), limit (optional, default 20, max 50), include_external (optional, default false).
Response: { "items": [{ "sequence": "1F600", "codepoints": ["1F600"], "is_emoji": true, "properties": ["Emoji_Presentation"], "cldr_short_name": "grinning face", "keywords": ["grinning", "face"] }] }

### Inventory Exists
POST /api/v1/datasets/emoji/inventory/exists
Body: { "sequence": "1F600" } or { "sequence": "1F468 200D 1F4BB" }
Check if a codepoint sequence exists in the Unicode emoji inventory.
Response: { "exists": true, "record": { "sequence": "1F600", "cldr_short_name": "grinning face", ... } }

### Keyword Search
GET /api/v1/datasets/emoji/keywords/search?q={query}&limit={limit}
Keyword-based emoji lookup from Emoji List v17.0.
Parameters: q (required), limit (optional, default 20, max 50).
Response: { "source": { "note": "Derived from Emoji List v17.0" }, "items": [{ "code": "U+1F525", "cldr_short_name": "fire", "matched": ["fire"] }] }

### Scoring Factors
GET /api/factors
Returns the 7 scoring factor definitions and tier boundaries.
Response: { "factors": [{ "key": "demand", "label": "Expected Usage (Demand)", "weight": 0.20, "maxScore": 100 }], "tiers": [{ "tier": "Excellent", "min": 80, "max": 100, "color": "#22c55e" }] }

### MCP Manifest
GET /.well-known/mcp.json
Static MCP tools manifest for AI agent discovery.

GET /api/mcp
Dynamic MCP manifest (same content, resolved at runtime for all environments).

### MCP Tools List
GET /api/v1/mcp/tools
Returns all MCP tools exposed by this site with full schema definitions.

### MCP Register
POST /api/v1/mcp/register
Registers this site's tools with the central PlatPhorm MCP registry.

### MCP Discover
GET /api/v1/mcp/discover?url={remote_url}
Discover MCP tools from the central registry or a specific remote site.

## MCP Tools

The following tools are available via the Model Context Protocol (MCP):

### score_emoji
Method: GET | Path: /api/emoji/score
Input: { "emoji": "string (required)" }
Scores a Unicode emoji character for popularity, versatility, and platform support. Returns overall score (0-100), tier classification, and per-factor breakdown.

### score_proposal
Method: POST | Path: /api/v1/emoji/score
Input: { "type": "score_request", "created_at": "ISO8601", "proposal": { ConceptDefinition } }
Evaluates an emoji concept against seven weighted criteria. Returns viability score, gate checks, and recommendations. Stateless.

### search_emoji
Method: GET | Path: /api/emoji/local-search
Input: { "q": "string", "group": "string", "limit": "integer (default 50)" }
Full-text search of the local Unicode emoji database by name, keyword, group, or code point.

### suggest_emoji
Method: GET | Path: /api/emoji/suggest
Input: { "q": "string (required)", "limit": "integer (default 8)" }
Typeahead suggestions for a partial emoji name query. Returns up to 8 emoji matching the prefix.

### get_timeline
Method: GET | Path: /api/emoji/timeline
Input: (none)
Returns all emoji grouped by the year they were added, with Unicode version labels, counts, and sample characters.

### get_recent_emoji
Method: GET | Path: /api/emoji/recent
Input: (none)
Returns emoji added in Unicode 15.1, 16.0 and 17.0, grouped by version.

### inventory_search
Method: GET | Path: /api/v1/datasets/emoji/inventory/search
Input: { "q": "string (required)", "limit": "integer (default 20)", "include_external": "boolean (default false)" }
Search the canonical Unicode emoji inventory. Returns structured records with codepoints, properties, CLDR short names, and keywords.

### inventory_exists
Method: POST | Path: /api/v1/datasets/emoji/inventory/exists
Input: { "sequence": "string (required)" }
Check whether a Unicode codepoint or sequence already exists in the emoji inventory.

### get_emoji_from_description
Method: GET | Path: /api/v1/emoji/from-description
Input: { "description": "string (required)", "limit": "integer (default 10)", "include_score": "boolean (default false)" }
Find emoji that match a natural-language description. Ideal for AI agents that need emoji based on text descriptions.

### health_check
Method: GET | Path: /api/v1/health
Input: (none)
Returns server status and current UTC time. Use to verify the API is reachable.

## Scoring Methodology

Emoji Score uses a 7-factor weighted model derived from Unicode Technical Standard #51:

1. **Expected Usage / Demand** (20%) — Frequency and breadth of anticipated use. High search volume, petition signatures, social media requests.
2. **Cross-cultural Universality** (15%) — Whether the concept is understood across cultures and languages.
3. **Semantic Gap** (20%) — The degree to which no existing emoji covers the concept.
4. **Longevity & Stability** (10%) — Likelihood the emoji remains relevant over time.
5. **Visual Distinctiveness** (15%) — Recognizable glyph at small sizes (18x18px).
6. **Inclusivity & Neutrality** (10%) — Freedom from branding, political, or cultural bias.
7. **Proposal Completeness** (10%) — Quality of documentation and supporting evidence.

### Proposal Score Tiers
- **Excellent** (80-100): Highly viable for Unicode submission.
- **Strong** (65-79): Strong candidate with minor improvements.
- **Moderate** (50-64): Promising but needs strengthening.
- **Needs Work** (35-49): Significant gaps to address.
- **Weak** (0-34): Major revisions recommended.

### Emoji Score Tiers
- **Highly Popular** (80+): Iconic emoji with universal recognition.
- **Popular** (65-79): Highly popular and widely used.
- **Moderate** (50-64): Moderately popular in specific contexts.
- **Niche** (35-49): Limited usage or specialized context.
- **Rarely Used** (0-34): Minimal usage or adoption.

## i18n Support

The site includes hreflang metadata for:
- English (en) — https://emoji.platphormnews.com/en
- Spanish (es) — https://emoji.platphormnews.com/es
- French (fr) — https://emoji.platphormnews.com/fr
- German (de) — https://emoji.platphormnews.com/de
- Japanese (ja) — https://emoji.platphormnews.com/ja
- Korean (ko) — https://emoji.platphormnews.com/ko
- Chinese (zh) — https://emoji.platphormnews.com/zh
- Arabic (ar) — https://emoji.platphormnews.com/ar
- Portuguese (pt) — https://emoji.platphormnews.com/pt

## MCP Integration

Emoji Score is registered with the PlatPhorm MCP Registry (https://mcp.platphormnews.com/api/mcp).
Every page includes: <link rel="mcp-registry" href="https://mcp.platphormnews.com/api/mcp" />

MCP tools available: score_emoji, score_proposal, search_emoji, suggest_emoji, get_timeline, get_recent_emoji, inventory_search, inventory_exists, get_emoji_from_description, health_check.

Discovery endpoints:
- Static manifest: https://emoji.platphormnews.com/.well-known/mcp.json
- Dynamic manifest: https://emoji.platphormnews.com/api/mcp
- Tools listing: https://emoji.platphormnews.com/api/v1/mcp/tools
- Registration: POST https://emoji.platphormnews.com/api/v1/mcp/register
- Discovery: GET https://emoji.platphormnews.com/api/v1/mcp/discover

## Network

Site: https://emoji.platphormnews.com
Network: https://www.platphormnews.com (*.platphormnews.com)
Publisher: PlatPhorm News
MCP Registry: https://mcp.platphormnews.com/api/mcp
Registry OpenAPI: https://mcp.platphormnews.com/openapi.yaml
OpenAPI: https://emoji.platphormnews.com/openapi/usl-emoji-validation.yaml
Contact: mailto:michael@barbineworldwide.com

## Data Sources

- Unicode emoji-test.txt v17.0 (primary): https://www.unicode.org/Public/emoji/latest/emoji-test.txt
- emoji-api.com (fallback for skin-tone variants and regional flags)
- Unicode ZWJ sequences: https://www.unicode.org/Public/emoji/latest/emoji-zwj-sequences.txt

## License

Emoji data © Unicode Consortium — https://www.unicode.org/copyright.html
Application code © PH3AR / PlatPhorm News. Not affiliated with the Unicode Consortium.