{"_id":"@dsottimano/trendspy-js","name":"@dsottimano/trendspy-js","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@dsottimano/trendspy-js","version":"0.1.0","description":"ALPHA VERSION: JavaScript port of trendspy - A library for analyzing Google Trends data","main":"dist/index.js","scripts":{"test":"jest","build":"babel src -d dist","prepare":"npm run build","prepublishOnly":"npm test"},"keywords":["google-trends","trends","analytics","search-trends"],"author":{"name":"David Sottimano"},"license":"MIT","dependencies":{"axios":"^1.6.7","axios-cookiejar-support":"^5.0.0","luxon":"^3.4.4","tough-cookie":"^4.1.3"},"devDependencies":{"@babel/cli":"^7.23.9","@babel/core":"^7.24.0","@babel/preset-env":"^7.24.0","jest":"^29.7.0"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/dsottimano/trendspy-js.git"},"bugs":{"url":"https://github.com/dsottimano/trendspy-js/issues"},"homepage":"https://github.com/dsottimano/trendspy-js#readme","_id":"@dsottimano/trendspy-js@0.1.0","_nodeVersion":"18.17.0","_npmVersion":"9.6.7","dist":{"integrity":"sha512-GB7jLTNaHNxJS75geID6OPZ+leP0SJ/EHYlxC6YUneE89pw/zylWuPZT9v7BmcTcldTCSM+t/0rXo29Ibz0BSw==","shasum":"cdfe0766454a5b0794f6c540865bc6f8b6867616","tarball":"https://registry.npmjs.org/@dsottimano/trendspy-js/-/trendspy-js-0.1.0.tgz","fileCount":11,"unpackedSize":144807,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCEdNSY9JfUjL9h1iqZwyyW/m74T01WPujbWv+OoW6/YQIgDzjHKXD0NDnVk5uIDu1RDJ4bFubRy7n1wNxRAbi4o2k="}]},"_npmUser":{"name":"dsottimano","email":"dsottimano@gmail.com"},"directories":{},"maintainers":[{"name":"dsottimano","email":"dsottimano@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/trendspy-js_0.1.0_1738155540179_0.4893862349660212"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-29T12:59:00.112Z","0.1.0":"2025-01-29T12:59:00.381Z","modified":"2025-01-29T12:59:00.582Z"},"maintainers":[{"name":"dsottimano","email":"dsottimano@gmail.com"}],"description":"ALPHA VERSION: JavaScript port of trendspy - A library for analyzing Google Trends data","homepage":"https://github.com/dsottimano/trendspy-js#readme","keywords":["google-trends","trends","analytics","search-trends"],"repository":{"type":"git","url":"git+https://github.com/dsottimano/trendspy-js.git"},"author":{"name":"David Sottimano"},"bugs":{"url":"https://github.com/dsottimano/trendspy-js/issues"},"license":"MIT","readme":"# trendspy-js\n\nA powerful JavaScript library for analyzing Google Trends data. This is a JavaScript port of the Python `trendspy` library, providing the same functionality with a JavaScript/Node.js-friendly interface.\n\n## Features\n\n- 📈 **Interest Over Time Analysis**: Track search interest trends across custom timeframes\n- 🔍 **Trending Searches**: Get real-time trending search terms\n- 🌍 **Geographic Data**: Support for region-specific trend analysis\n- ⏰ **Flexible Timeframes**: Multiple time range formats with automatic resolution handling\n- 🔄 **Rate Limiting**: Built-in rate limiting and retry mechanisms\n- 📊 **Data Processing**: Tools for processing and analyzing trends data\n\n## Installation\n\n```bash\nnpm install trendspy-js\n```\n\n## Quick Start\n\n```javascript\nconst { Trends } = require('trendspy-js');\n\nasync function main() {\n    // Initialize with options\n    const trends = new Trends({\n        language: 'en',\n        tz: -440,  // Timezone offset in minutes\n        requestDelay: 8.0,  // Delay between requests in seconds\n        maxRetries: 3\n    });\n\n    try {\n        // Get interest over time for keywords\n        const data = await trends.interestOverTime(['NBA', 'basketball'], {\n            geo: 'US',\n            timeframe: 'now 4-H'  // Last 4 hours\n        });\n\n        console.log(data);\n    } catch (error) {\n        console.error('Error:', error.message);\n    }\n}\n\nmain();\n```\n\n## Timeframe Formats\n\nThe library supports various timeframe formats:\n\n```javascript\n// Fixed timeframes\n'now 1-H'    // Last hour\n'now 4-H'    // Last 4 hours\n'now 1-d'    // Last day\n'now 7-d'    // Last 7 days\n'today 1-m'  // Last month\n'today 3-m'  // Last 3 months\n'today 12-m' // Last year\n'all'        // All available data\n\n// Custom date ranges\n'2024-03-15 2024-03-16'           // Specific dates\n'2024-03-15T14 2024-03-15T18'     // Specific dates with hours\n\n// Relative timeframes\n'2024-03-15 1-H'     // One hour before March 15, 2024\n'2024-03-15T14 5-H'  // 5 hours before 2PM on March 15, 2024\n'2024-03-15 1-m'     // One month before March 15, 2024\n'2024-03-15 1-y'     // One year before March 15, 2024\n```\n\n## API Reference\n\n### Trends Class\n\n#### Constructor Options\n```javascript\n{\n    language: string,     // Language code (default: 'en')\n    tz: number,          // Timezone offset in minutes\n    requestDelay: number, // Delay between requests in seconds\n    maxRetries: number   // Maximum number of retry attempts\n}\n```\n\n#### Methods\n\n##### interestOverTime(keywords, options)\n```javascript\n// Input options\nconst options = {\n    geo: string,           // Geographic location (e.g., 'US')\n    timeframe: string,     // Time range to analyze\n    category: number,      // Category ID (optional)\n    property: string,      // Property filter (optional)\n    resolution: string     // Time resolution (optional)\n};\n\n// Response format\n{\n    \"timestamps\": [\n        1710432000000,  // Unix timestamps in milliseconds\n        1710433800000,\n        // ...\n    ],\n    \"values\": {\n        \"NBA\": [\n            45,        // Interest values (0-100)\n            62,\n            // ...\n        ],\n        \"basketball\": [\n            38,\n            57,\n            // ...\n        ]\n    },\n    \"averages\": {      // Average interest over the timeframe\n        \"NBA\": 52.5,\n        \"basketball\": 48.2\n    },\n    \"timeframe\": {\n        \"start\": \"2024-03-14T12:00:00-04:00\",\n        \"end\": \"2024-03-14T16:00:00-04:00\",\n        \"resolution\": \"1 minute\"\n    }\n}\n```\n\n##### trendingSearches(options)\n```javascript\n// Input options\nconst options = {\n    geo: string,           // Geographic location\n    date: string,         // Date to get trends for\n    category: string      // Category filter (optional)\n};\n\n// Response format\n{\n    \"trending\": [\n        {\n            \"keyword\": \"March Madness\",\n            \"traffic\": \"1M+\",\n            \"trendKeywords\": [\"NCAA\", \"basketball\", \"tournament\"],\n            \"news\": [\n                {\n                    \"title\": \"March Madness 2024: Latest Updates\",\n                    \"link\": \"https://example.com/news\",\n                    \"source\": \"Sports News\",\n                    \"publishedAt\": \"2024-03-14T15:30:00Z\"\n                }\n            ],\n            \"startedAt\": \"2024-03-14T12:00:00Z\"\n        },\n        // ... more trending items\n    ],\n    \"date\": \"2024-03-14\",\n    \"geo\": \"US\"\n}\n```\n\n##### trendingNowShowcaseTimeline(keywords, options)\n```javascript\n// Input options\nconst options = {\n    geo: string,           // Geographic location\n    timeframe: string,     // Time range to analyze\n    category: string      // Category filter (optional)\n};\n\n// Response format\n{\n    \"timeline\": [\n        {\n            \"timestamp\": \"2024-03-14T12:00:00Z\",\n            \"trends\": [\n                {\n                    \"keyword\": \"NBA\",\n                    \"rank\": 1,\n                    \"volume\": \"500K+\",\n                    \"status\": \"rising\"\n                },\n                // ... more trends\n            ]\n        },\n        // ... more timeline entries\n    ],\n    \"metadata\": {\n        \"timeframe\": {\n            \"start\": \"2024-03-14T12:00:00Z\",\n            \"end\": \"2024-03-14T16:00:00Z\",\n            \"resolution\": \"16 minutes\"\n        },\n        \"geo\": \"US\"\n    }\n}\n```\n\n### Utility Functions\n\n#### Timeframe Utilities\n\n```javascript\nconst { convertTimeframe, timeframeToDuration } = require('trendspy-js');\n\n// Convert timeframe to API format\nconst apiTimeframe = convertTimeframe('2024-03-15 1-H');\n// Returns: \"2024-03-15T00 2024-03-15T01\"\n\n// Get duration object\nconst duration = timeframeToDuration('now 4-H');\n// Returns Luxon Duration object: { hours: 4 }\n```\n\n#### Hierarchical Search\n\n```javascript\nconst { HierarchicalIndex } = require('trendspy-js');\n\n// Sample data structure\nconst items = [\n    { name: \"United States\", id: \"US\" },\n    { name: \"New York\", id: \"US-NY\" }\n];\n\n// Create search index\nconst index = new HierarchicalIndex(items);\n\n// Search by name\nconst result = index.exactSearch('United States');\n// Returns: { name: \"United States\", id: \"US\" }\n\n// Partial search\nconst matches = index.partialSearch('Unit');\n// Returns: [{ name: \"United States\", id: \"US\" }]\n\n// ID search\nconst locationMatch = index.idSearch('US-NY');\n// Returns: [{ name: \"New York\", id: \"US-NY\" }]\n```\n\n## Error Handling\n\nThe library includes built-in error handling for common scenarios:\n\n```javascript\ntry {\n    const data = await trends.interestOverTime(['keyword'], {\n        geo: 'US',\n        timeframe: 'now 1-H'\n    });\n} catch (error) {\n    if (error.name === 'TrendsQuotaExceededError') {\n        console.log('Rate limit exceeded. Try increasing requestDelay.');\n    } else if (error.name === 'TrendsRequestError') {\n        console.log('API request failed:', error.message);\n    } else {\n        console.log('Unexpected error:', error);\n    }\n}\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build package\nnpm run build\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT\n\n## Acknowledgments\n\nThis is a JavaScript port of the Python [trendspy](https://github.com/example/trendspy) library. ","readmeFilename":"README.md"}