compare-audience-influencers

Compare influencer affinities and uniqueness between a selected audience and a baseline audience to identify distinct alignment patterns.

Instructions

Compares the influencers of an audience with a baseline audience. The baseline is determined as follows: If the selection was the full audience and a single country represents more than 50% of the audience, that country is used as the baseline. Otherwise, the Global baseline is applied. If the selection was a specific segment, the full audience is used as the baseline. Each influencer comparison includes: - Affinity (%) - The level of alignment between the influencer and the audience. Baseline Affinity (%) - The influencer’s affinity within the baseline audience. Uniqueness Score - A measure of how distinct the influencer is within the selected audience compared to the baseline.

Input Schema

TableJSON Schema

Name	Required	Description
`audience_influencers_id`	Yes	The ID of the audience influencers.
`baseline_audience_influencers_id`	Yes	The ID of the baseline audience influencers.
`cursor`	No	Cursor for pagination.
`count`	No	Number of items per page (default: 200).
`bio_keyword`	No	Keyword to filter influencers by their biography.
`entity_type`	No	Filter by entity type (person or brand).
`followers_min`	No	Minimum number of followers.
`followers_max`	No	Maximum number of followers.
`categories`	No	Filter influencers by categories.
`countries`	No	Filter influencers by country ISO codes.

Implementation Reference

src/audienseClient.ts:189-234 (handler)

Core handler function that constructs the Audiense API endpoint for comparing audience influencers, fetches the data, and enriches the top 100 influencers with Twitter/X user details.

export async function compareAudienceInfluencers(
    audience_influencers_id: string,
    baseline_audience_influencers_id: string,
    cursor?: number,
    count?: number,
    bio_keyword?: string,
    entity_type?: "person" | "brand",
    followers_min?: number,
    followers_max?: number,
    categories?: string[],
    countries?: string[]
): Promise<{ cursor: { next: number; prev: number }; influencers: any[] } | null> {
    const queryParams = new URLSearchParams();

    if (cursor !== undefined) queryParams.append("cursor", cursor.toString());
    if (count !== undefined) queryParams.append("count", count.toString());
    if (bio_keyword) queryParams.append("bio_keyword", bio_keyword);
    if (entity_type) queryParams.append("entity_type", entity_type);
    if (followers_min !== undefined) queryParams.append("followers_min", followers_min.toString());
    if (followers_max !== undefined) queryParams.append("followers_max", followers_max.toString());
    if (categories && categories.length > 0) queryParams.append("categories", categories.join(","));
    if (countries && countries.length > 0) queryParams.append("countries", countries.join(","));

    const endpoint = `/audience_influencers/${audience_influencers_id}/compared_to/${baseline_audience_influencers_id}?${queryParams.toString()}`;

    const data = await makeAudienseRequest<{ cursor: { next: number; prev: number }; influencers: { id: string; affinity: number; baseline_affinity: number; uniqueness: number }[] }>(endpoint);

    if (!data || !data.influencers.length) {
        return data;
    }

    // Get the first 100 influencers for enrichment
    const influencerIds = data.influencers.slice(0, 100).map((influencer) => influencer.id);
    const twitterData = await fetchTwitterUserDetails(influencerIds);

    // Merge Twitter details into influencer data
    const enrichedInfluencers = data.influencers.map((influencer) => ({
        ...influencer,
        twitter: twitterData[influencer.id] || null, // Add Twitter data if available
    }));

    return {
        cursor: data.cursor,
        influencers: enrichedInfluencers,
    };
}

src/index.ts:194-257 (registration)

MCP server.tool registration for the 'compare-audience-influencers' tool, including description, input schema (Zod validation), and thin wrapper handler that calls the core compareAudienceInfluencers function and formats the MCP response.

server.tool(
    "compare-audience-influencers",
    `Compares the influencers of an audience with a baseline audience. The baseline is determined as follows: 
    If the selection was the full audience and a single country represents more than 50% of the audience, that country is used as the baseline.
    Otherwise, the Global baseline is applied. If the selection was a specific segment, the full audience is used as the baseline.
    Each influencer comparison includes: 
        - Affinity (%) - The level of alignment between the influencer and the audience. Baseline Affinity (%)
        - The influencer’s affinity within the baseline audience. Uniqueness Score
        - A measure of how distinct the influencer is within the selected audience compared to the baseline.
    `,
    {
        audience_influencers_id: z.string().describe("The ID of the audience influencers."),
        baseline_audience_influencers_id: z.string().describe("The ID of the baseline audience influencers."),
        cursor: z.number().optional().describe("Cursor for pagination."),
        count: z.number().optional().describe("Number of items per page (default: 200)."),
        bio_keyword: z.string().optional().describe("Keyword to filter influencers by their biography."),
        entity_type: z.enum(["person", "brand"]).optional().describe("Filter by entity type (person or brand)."),
        followers_min: z.number().optional().describe("Minimum number of followers."),
        followers_max: z.number().optional().describe("Maximum number of followers."),
        categories: z.array(z.string()).optional().describe("Filter influencers by categories."),
        countries: z.array(z.string()).optional().describe("Filter influencers by country ISO codes."),
    },
    async ({ audience_influencers_id, baseline_audience_influencers_id, cursor, count, bio_keyword, entity_type, followers_min, followers_max, categories, countries }) => {
        const data = await compareAudienceInfluencers(
            audience_influencers_id,
            baseline_audience_influencers_id,
            cursor,
            count,
            bio_keyword,
            entity_type,
            followers_min,
            followers_max,
            categories,
            countries
        );

        if (!data || !data.influencers.length) {
            return {
                content: [
                    {
                        type: "text",
                        text: `No influencers found for comparison between ${audience_influencers_id} and ${baseline_audience_influencers_id}.`,
                    },
                ],
            };
        }

        const influencersText = data.influencers
            .map(
                (influencer) =>
                    `ID: ${influencer.id}\nAffinity: ${influencer.affinity}%\nBaseline Affinity: ${influencer.baseline_affinity}%\nUniqueness: ${influencer.uniqueness}%`
            )
            .join("\n\n");

        return {
            content: [
                {
                    type: "text",
                    text: JSON.stringify(data, null, 2),
                },
            ],
        };
    }
);

src/index.ts:204-215 (schema)

Zod schema for input parameters validation in the MCP tool registration.

{
    audience_influencers_id: z.string().describe("The ID of the audience influencers."),
    baseline_audience_influencers_id: z.string().describe("The ID of the baseline audience influencers."),
    cursor: z.number().optional().describe("Cursor for pagination."),
    count: z.number().optional().describe("Number of items per page (default: 200)."),
    bio_keyword: z.string().optional().describe("Keyword to filter influencers by their biography."),
    entity_type: z.enum(["person", "brand"]).optional().describe("Filter by entity type (person or brand)."),
    followers_min: z.number().optional().describe("Minimum number of followers."),
    followers_max: z.number().optional().describe("Maximum number of followers."),
    categories: z.array(z.string()).optional().describe("Filter influencers by categories."),
    countries: z.array(z.string()).optional().describe("Filter influencers by country ISO codes."),
},

Audiense Insights MCP Server