@arraypress/referrer

Parse referrer URLs to detect traffic sources, search engines, social platforms, and UTM campaign parameters. Designed for analytics and traffic attribution in ecommerce and SaaS applications.

Zero dependencies. Works in Node.js, Cloudflare Workers, Deno, Bun, and browsers.

Installation

npm install @arraypress/referrer

Usage

import { getSource, getTrafficType, getSearchTerms, getUtmParams } from '@arraypress/referrer';

// Identify the traffic source
getSource('https://www.google.com/search?q=test');  // 'google'
getSource('https://t.co/abc123');                    // 'twitter'
getSource('https://some-blog.com/post');             // 'referral'
getSource('');                                        // 'direct'

// Categorize traffic type
getTrafficType('https://google.com/search?q=test');             // 'search'
getTrafficType('https://facebook.com/post/123');                // 'social'
getTrafficType('https://blog.com/?utm_source=newsletter');      // 'campaign'
getTrafficType('https://random-blog.com/article');              // 'referral'
getTrafficType('');                                              // 'direct'

// Extract search terms
getSearchTerms('https://google.com/search?q=best+sample+packs');  // 'best sample packs'
getSearchTerms('https://facebook.com/post');                       // null

// Extract UTM parameters
getUtmParams('https://store.com/?utm_source=newsletter&utm_medium=email&utm_campaign=launch');
// { source: 'newsletter', medium: 'email', campaign: 'launch', term: null, content: null }

API

getSource(url: string): string

Returns the specific traffic source. For recognized platforms, returns the platform name (e.g. 'google', 'facebook', 'reddit'). For unknown domains returns 'referral'. For empty/null input returns 'direct'.

getTrafficType(url: string): TrafficType

Returns the broad traffic category: 'search', 'social', 'campaign', 'referral', or 'direct'.

UTM parameters take precedence — if any UTM param is present, returns 'campaign' regardless of the domain. This means https://google.com/?utm_source=promo returns 'campaign', not 'search'.

getSearchTerms(url: string): string | null

Extracts the search query from a search engine referrer URL. Returns null if the URL is not from a recognized search engine or has no query parameter.

Checks these query parameters: q, query, p, wd, text.

Note: Many search engines (especially Google) no longer pass search terms in the referrer URL for privacy reasons.

getUtmParams(url: string): UtmParams

Extracts UTM campaign parameters. Always returns an object with all five fields; missing parameters are null.

interface UtmParams {
  source: string | null;    // utm_source
  medium: string | null;    // utm_medium
  campaign: string | null;  // utm_campaign
  term: string | null;      // utm_term
  content: string | null;   // utm_content
}

Supported Platforms

Search Engines (18): Google (30+ regional domains), Bing, Yahoo, DuckDuckGo, Baidu, Yandex, Ecosia, Startpage, Brave, Ask, AOL, Searx, Perplexity, You.com, Phind, Kagi, SearchGPT/ChatGPT, DeepSeek.

Social Platforms (15): Facebook, Twitter/X, Instagram, LinkedIn, Pinterest, Reddit, YouTube, TikTok, Snapchat, Discord, Telegram, WhatsApp, Mastodon, Threads, Bluesky.

All platforms include mobile variants, short link domains (t.co, fb.me, youtu.be, etc.), and regional subdomains.

Recommended Pattern

Store the raw referrer URL in your database and parse it on read. This preserves the original data and automatically benefits from future platform updates.

// At checkout — capture and store raw URL
const referrer = request.headers.get('referer') || '';
await db.prepare('UPDATE orders SET referrer = ? WHERE id = ?')
  .bind(referrer, orderId).run();

// In reports — parse on read
import { getSource, getTrafficType } from '@arraypress/referrer';

const source = getSource(order.referrer);  // 'google'
const type = getTrafficType(order.referrer);  // 'search'

TypeScript

Full type definitions are included.

import { getSource, getTrafficType, getUtmParams } from '@arraypress/referrer';
import type { TrafficType, UtmParams } from '@arraypress/referrer';

const source: string = getSource(url);
const type: TrafficType = getTrafficType(url);
const utm: UtmParams = getUtmParams(url);

License

MIT