Core Concepts

Before making requests, it helps to understand a few core concepts that shape how Yoku works.

Identifiers

Yoku accepts multiple identifiers to resolve a company or brand:

• Domain (e.g. stripe.com)
• Company name (e.g. Stripe)
• Stock ticker (e.g. AAPL)
• Transaction string (e.g. AMZN*MKTP)

All identifiers are normalized internally into a single brand entity.

Brand Entity

A brand entity represents a real-world company or organization.

It may include:

• One or more domains
• Multiple brand assets (logos, colors)
• Public descriptions and metadata
• Social presence
• Industry classification

Yoku continuously reconciles and updates these entities.

Real-time vs cached data

Yoku prioritizes speed and consistency.

• Frequently requested brands are served from cache
• New or uncommon brands may trigger background enrichment
• Responses are versioned and normalized to stay stable over time

This means you get predictable responses without managing refresh logic yourself.

The Brand Entity System

At Yoku's core is the Brand Entity - a normalized representation of a real-world company or organization. Each entity is a living record that continuously updates as brands evolve their visual identity.

How Entities Are Created

1. Initial Discovery - When you request a new identifier that is not part of the 8+ million brands in our database, Yoku initiates a discovery process
2. Multi-Source Aggregation - Data is gathered from websites, public registries, financial databases, and social platforms automatically
3. Normalization - Conflicting information is resolved, duplicates are merged, and a canonical representation emerges
4. Continuous Enrichment - Background processes keep entities current as brands update their identity

Entity Components

Each brand entity includes these key components:

interface BrandEntity {
  // Core Identification
  identifiers: Array<{
    type: "domain" | "company_name" | "ticker" | "transaction" | "registry_id";
    value: string;
    isPrimary: boolean;
  }>;

  // Visual Identity
  visualIdentity: {
    logos: Logo[];
    colorPalette: Color[];
    typography: Font[];
    imagery: BrandAsset[];
  };

  // Company Context
  metadata: {
    name: string;
    description: string;
    industry: IndustryClassification;
    locations: Address[];
    socialProfiles: SocialProfile[];
  };

  // System Metadata
  system: {
    confidenceScore: number;
    lastUpdated: DateTime;
    sourceCount: number;
    reviewStatus: "verified" | "pending" | "unverified";
  };
}

Identifier Resolution System

Yoku accepts multiple identifier types and intelligently maps them to the correct brand entity:

1. Domain-Based Resolution

Input: "stripe.com"
Process:
  → Normalize domain (strip protocol, www)
  → Check domain aliases (stripe.io, stripe.org)
  → Verify organizational ownership
  → Return Stripe brand entity

2. Company Name Resolution

Input: "Amazon"
Challenges:
  - Multiple companies share names
  - International variations exist
  - Acronyms vs. full names
Solution:
  → Disambiguation via location context
  → Industry filtering when available
  → Confidence scoring for matches

3. Financial Identifier Resolution

Input: "AAPL"
Process:
  → Map ticker to ISIN/US0378331005
  → Resolve to Apple Inc. entity
  → Enrich with SEC filings data
  → Include investor relations assets

4. Transaction String Resolution

Input: "AMZN*MKTP AMAZON.COM"
Process:
  → Parse merchant descriptor patterns
  → Extract normalized merchant name
  → Match to Amazon.com entity
  → Return consumer-facing brand presentation

Cache Tiers

• Level 1: Memory cache (millisecond response, 5-minute TTL)
• Level 2: Redis cache (sub-100ms response, 24-hour TTL)
• Level 3: Database cache (fast response, 7-day TTL)
• Level 4: Real-time fetch (variable response, triggers background job)

Staleness Handling

• High-traffic brands (Apple, Google): Updated daily via scheduled jobs
• Medium-traffic brands: Updated weekly or on cache miss
• Low-traffic brands: Updated on-demand with background refresh
• Breaking changes (rebrands, acquisitions): Manual override capability

Confidence Scoring System

Each data point includes a confidence score indicating reliability: