README

A PHP library for interacting with the Google Trends API. This package provides a simple and type-safe way to access Google Trends data programmatically.

This is a PHP port of the TypeScript library @shaivpidadi/trends-js, maintaining identical functionality and behavior.

Installation

composer require maximeb97/trends-php

Requirements

PHP >= 7.4
cURL extension enabled

Features

Get daily trending topics
Get real-time trending topics
Get autocomplete suggestions
Explore trends data
Get interest by region data
Get related topics for any keyword
Get related queries for any keyword
Get combined related data (topics + queries)
Full error handling with custom exceptions

Usage

Basic Usage

<?php

require_once 'vendor/autoload.php';

use Maximeb97\GoogleTrends\GoogleTrends;

// Get daily trends
$result = GoogleTrends::dailyTrends(['geo' => 'US', 'lang' => 'en']);

if (isset($result['data'])) {
    $trends = $result['data'];
    foreach ($trends->allTrendingStories as $story) {
        echo $story->title . " - Traffic: " . $story->traffic . "\n";
    }
} else {
    echo "Error: " . $result['error']->getMessage() . "\n";
}

Daily Trends

Get daily trending topics for a specific region:

use Maximeb97\GoogleTrends\GoogleTrends;

$result = GoogleTrends::dailyTrends([
    'geo' => 'US',  // Default: 'US'
    'lang' => 'en', // Default: 'en'
]);

// Result structure:
// [
//   'data' => DailyTrendingTopics {
//     allTrendingStories: TrendingStory[],
//     summary: TrendingTopic[]
//   }
// ]
// or
// ['error' => GoogleTrendsError]

Real-Time Trends

Get real-time trending topics:

use Maximeb97\GoogleTrends\GoogleTrends;
use Maximeb97\GoogleTrends\Types\GoogleTrendsTrendingHours;

$result = GoogleTrends::realTimeTrends([
    'geo' => 'US', // Default: 'US'
    'trendingHours' => GoogleTrendsTrendingHours::FOUR_HOURS, // Default: 4
]);

// Available trending hours:
// - GoogleTrendsTrendingHours::FOUR_HOURS (4)
// - GoogleTrendsTrendingHours::ONE_DAY (24)
// - GoogleTrendsTrendingHours::TWO_DAYS (48)
// - GoogleTrendsTrendingHours::SEVEN_DAYS (168)

Autocomplete

Get search suggestions for a keyword:

$result = GoogleTrends::autocomplete(
    'bitcoin',  // Keyword to get suggestions for
    'en-US'     // Language (default: 'en-US')
);

// Returns: ['data' => string[]] or ['error' => GoogleTrendsError]
if (isset($result['data'])) {
    print_r($result['data']); // Array of suggestion strings
}

Explore

Get widget data for a keyword:

$result = GoogleTrends::explore([
    'keyword' => 'bitcoin',
    'geo' => 'US',           // Default: 'US'
    'time' => 'today 12-m',  // Default: 'today 12-m'
    'category' => 0,         // Default: 0
    'property' => '',        // Default: ''
    'hl' => 'en-US',        // Default: 'en-US'
]);

// Returns: ['widgets' => array] or ['error' => GoogleTrendsError]

Interest By Region

Get interest data by geographic region:

$result = GoogleTrends::interestByRegion([
    'keyword' => 'bitcoin',
    'startTime' => new DateTime('2023-01-01'), // Default: new DateTime('2004-01-01')
    'endTime' => new DateTime(),               // Default: now
    'geo' => 'US',                            // Default: 'US'
    'resolution' => 'REGION',                 // Default: 'REGION' (can be 'COUNTRY', 'REGION', 'CITY', 'DMA')
    'hl' => 'en-US',                         // Default: 'en-US'
    'timezone' => 0,                          // Default: current timezone offset
    'category' => 0,                          // Default: 0
]);

// Returns: array with geoMapData or ['error' => GoogleTrendsError]

Related Queries

Get related queries for a keyword:

$result = GoogleTrends::relatedQueries([
    'keyword' => 'bitcoin',
    'geo' => 'US',          // Default: 'US'
    'time' => 'now 1-d',    // Default: 'now 1-d'
    'hl' => 'en-US',       // Default: 'en-US'
]);

// Returns: ['data' => ['default' => ['rankedList' => [...]]]] or ['error' => GoogleTrendsError]
if (isset($result['data'])) {
    $rankedList = $result['data']['default']['rankedList'];
    foreach ($rankedList as $list) {
        foreach ($list['rankedKeyword'] as $query) {
            echo $query['query'] . " - " . $query['formattedValue'] . "\n";
        }
    }
}

Related Data (Combined)

Get combined related topics and queries:

$result = GoogleTrends::relatedData([
    'keyword' => 'bitcoin',
    'geo' => 'US',          // Default: 'US'
    'time' => 'now 1-d',    // Default: 'now 1-d'
    'hl' => 'en-US',       // Default: 'en-US'
]);

// Returns: ['data' => ['topics' => [...], 'queries' => [...]]] or ['error' => GoogleTrendsError]
if (isset($result['data'])) {
    echo "Related Topics:\n";
    foreach ($result['data']['topics'] as $topic) {
        echo "  - " . $topic['topic']['title'] . "\n";
    }
    
    echo "\nRelated Queries:\n";
    foreach ($result['data']['queries'] as $query) {
        echo "  - " . $query['query'] . "\n";
    }
}

Error Handling

The library uses custom exception classes for different error types:

use Maximeb97\GoogleTrends\Errors\RateLimitError;
use Maximeb97\GoogleTrends\Errors\InvalidRequestError;
use Maximeb97\GoogleTrends\Errors\NetworkError;
use Maximeb97\GoogleTrends\Errors\ParseError;
use Maximeb97\GoogleTrends\Errors\UnknownError;

$result = GoogleTrends::dailyTrends(['geo' => 'US']);

if (isset($result['error'])) {
    $error = $result['error'];
    
    if ($error instanceof RateLimitError) {
        echo "Rate limit exceeded. Please try again later.\n";
    } elseif ($error instanceof NetworkError) {
        echo "Network error: " . $error->getMessage() . "\n";
    } elseif ($error instanceof ParseError) {
        echo "Failed to parse response: " . $error->getMessage() . "\n";
    } else {
        echo "Error: " . $error->getMessage() . "\n";
    }
    
    // Get error code
    echo "Error code: " . $error->getErrorCode() . "\n";
    
    // Get status code (if available)
    if ($error->getStatusCode()) {
        echo "HTTP status: " . $error->getStatusCode() . "\n";
    }
}

Object-Oriented Usage

You can also use the GoogleTrendsApi class directly:

use Maximeb97\GoogleTrends\GoogleTrendsApi;

$api = new GoogleTrendsApi();
$result = $api->dailyTrends(['geo' => 'US']);

if (isset($result['data'])) {
    // Process data
}

Data Structures

TrendingStory

class TrendingStory {
    public string $title;
    public string $traffic;
    public ?TrendingImage $image;
    public array $articles;  // TrendingArticle[]
    public string $shareUrl;
}

TrendingArticle

class TrendingArticle {
    public string $title;
    public string $url;
    public string $source;
    public string $time;
    public string $snippet;
}

TrendingImage

class TrendingImage {
    public string $newsUrl;
    public string $source;
    public string $imageUrl;
}

Time Formats

The library supports various time formats for the time parameter:

'now 1-d' - Past day
'now 7-d' - Past 7 days
'today 1-m' - Past month
'today 3-m' - Past 3 months
'today 12-m' - Past 12 months
'today 5-y' - Past 5 years
'all' - All available data (2004-present)
Custom: 'YYYY-MM-DD YYYY-MM-DD' - Specific date range

License

MIT

Credits

This is a PHP port of @shaivpidadi/trends-js.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

maximeb97 / trends-php

Maintainers

Details