​

CreatorDB Naming Convention Recommendations

These recommendations address the open naming convention items (Rules 2-6) from the WIP audit, now informed by competitor API analysis.

---

​

Rule 2: Follower / Subscriber Naming in Cross-Platform Endpoints

Current CreatorDB names:

• YouTube: totalSubscribers, subscriberGrowth, likesPerSubscriber
• Instagram: totalFollowers, followerGrowthIn30d, likesPerFollower

Industry pattern:

• HypeAuditor: followers_count (IG) / subscribers_count (YT) — platform-specific
• Phyllo: follower_count (IG) / subscriber_count (YT) — platform-specific
• Modash: followers for all platforms — universal term

Assessment: 2 of 3 competitors with data use platform-specific terms, matching CreatorDB’s approach. This is already documented as an intentional cross-platform difference. Recommendation: KEEP CURRENT NAMES. No change needed.

---

​

Rule 3: Display Name (displayName vs username)

Current CreatorDB names:

• YouTube: displayName (profile), displayName (search)
• Instagram: username (profile), username (search)

Industry pattern:

• HypeAuditor: full_name for display name
• Phyllo: full_name for display name
• Both use username to mean “handle” (the opposite of CreatorDB IG’s usage)

Assessment: CreatorDB Instagram using username for display name is actively misleading. Every competitor uses username to mean “handle/platform ID.” A developer coming from HypeAuditor or Phyllo will expect username to return the handle, not the display name. YouTube’s displayName is clear and self-documenting, even though it differs from the industry’s full_name. The word “display” in the name makes the meaning unambiguous. Recommendation: RENAME Instagram username to displayName across all IG endpoints (profile, search).

---

​

Rule 4: Creator Handle / Platform ID Naming

Current CreatorDB names:

• YouTube: uniqueId (handle like @mrbeast), channelId (YT internal ID like UCBR8…)
• Instagram: userId (handle like goodalicia)

Industry pattern:

• HypeAuditor: username for handle
• Phyllo: platform_username for handle
• Modash: userId for identifier (ambiguous whether handle or internal ID)

Assessment: The industry prefers username for handle, but CreatorDB has a complication: it has two ID types on YouTube (a human-readable handle AND a platform-assigned channel ID). The handle needs a different name from the channel ID. Current problems:

1. uniqueId (YT) does not communicate “handle” — it sounds like a database primary key
2. userId (IG) also does not communicate “handle” — same problem
3. The two platforms use different names for the same concept

Recommendation: This is a harder change to make because the current param names (channelId, userId) are used as query parameters in GET requests and changing them is a significant breaking change. For response fields (what appears in profile/search responses), the ideal names would be:

• YouTube handle: handle or username (with channelId remaining as the YT-assigned ID)
• Instagram handle: handle or username

However, since these are also the primary lookup parameters for GET endpoints (?userId=goodalicia), renaming has a large blast radius.

---

​

Rule 5: Sponsorship Array Naming (sponsorList vs sponsoredContent)

Current CreatorDB names:

• YouTube (pricing ref): sponsoredContent[]
• Instagram: sponsorList[]

Industry pattern:

• HypeAuditor: advertising_data.brand_mentions[]
• No other competitor has detailed field-level sponsorship data publicly documented

Assessment: There is no industry consensus to follow here. The real problem is internal inconsistency between YouTube and Instagram. Both need to use the same name since they represent the same concept (a list of brands that have sponsored the creator, with nested content per brand). Evaluating the two candidates:

• sponsorList — emphasizes the list-of-brands structure. Clear but the word “list” is redundant (it is already an array).
• sponsoredContent — emphasizes the content. But the array is grouped by brand, not by content piece, so this name is slightly misleading.

Recommendation: USE sponsorList on both platforms.

---

​

Rule 6: Per-Follower / Per-Subscriber Metric Naming

Current CreatorDB names:

• YouTube: likesPerSubscriber, commentsPerSubscriber, viewsPerSubscriber
• Instagram: likesPerFollower, commentsPerFollower, viewsPerFollower

Industry pattern:

• No competitor publicly exposes per-follower ratio fields
• This is a CreatorDB differentiator

Assessment: Since there is no industry precedent, the naming should follow CreatorDB’s own internal conventions. The current approach uses platform-specific terms (PerSubscriber for YT, PerFollower for IG), which mirrors the totalSubscribers/totalFollowers convention. This is consistent and correct. Recommendation: KEEP CURRENT NAMES. No change needed.

---

​

Summary of Recommendations

​

Recommended Implementation Order

1. Rule 5 (sponsorship arrays) — fix the YT pricing reference now, before fractional calls ship. Lowest blast radius of the breaking changes.
2. Rule 3 (display name) — fix IG username to displayName. This is the most developer-facing confusion. Plan a deprecation cycle.
3. Rule 4 (handle naming) — can be deferred. Document the current convention clearly in the meantime. Schedule for a future API version if a major version bump is planned.