🎵 ytlookup

Blazing-fast async YouTube search library

✨ Why ytlookup?

⚡ Blazing fast: Typical response time is around 50-100ms with optimized InnerTube requests.
🔐 No API key needed: Zero setup, no quotas, and no external credential configuration.
🎯 Simple developer experience: Clean async API with typed return structures and predictable fields.
🚀 Production-ready by design: Includes robust parsing, fallback handling, and stable response formatting.
🐍 Modern Python support: Works on Python 3.8-3.14 with a minimal dependency footprint (aiohttp).

📦 Installation

Quick Install

pip install ytlookup

From Source

git clone https://github.com/CertifiedCoders/ytlookup
cd ytlookup
pip install -e .

Requirements: Python 3.8+ and aiohttp

🚀 Quick Start

Get Video Information (Fast Mode)

import asyncio
from ytlookup import Video

async def main():
    # Lightning fast - ~50ms response time! ⚡
    video = await Video.get("dQw4w9WgXcQ")
    
    print(f"📹 {video['title']}")
    print(f"👤 {video['channel']['name']}")
    print(f"👁️  {video['viewCount']['short']}")
    print(f"⏱️  {video['duration']['text']}")

asyncio.run(main())

Get Complete Information (With Extras)

import asyncio
from ytlookup import Video

async def main():
    # Includes publishedTime and may include likes (~500ms)
    video = await Video.get("dQw4w9WgXcQ", fetch_extras=True)
    if not video:
        print("Video not found")
        return

    print(f"📅 Published: {video.get('publishedTime', 'N/A')}")
    likes = video.get("likesCount", {}).get("short", "N/A")
    print(f"👍 Likes: {likes}")

asyncio.run(main())

Search YouTube Videos

import asyncio
from ytlookup import videosearch

async def main():
    # Search with metadata
    videos = await videosearch("Python tutorial", limit=5)

    for video in videos:
        print(f"🎬 {video['title']}")
        print(f"   📊 {video['viewCount']['short']} • {video['duration']['text']}")
        print(f"   🔗 {video['url']}\n")

asyncio.run(main())

Get Playlist Information

import asyncio
from ytlookup import Playlist

async def main():
    # Fetch playlist with videos
    playlist = await Playlist.get("PLxxx...", limit=10)
    if not playlist:
        print("Playlist not found")
        return

    print(f"📋 {playlist['title']}")
    print(f"🎬 {playlist['videoCount']} videos")
    print(f"👤 {playlist['channel']['name']}")

    for video in playlist['videos']:
        print(f"  • {video['title']}")

asyncio.run(main())

📚 Detailed Guide

For complete API contracts, response shapes, and advanced usage patterns, see DOCUMENTATION.md.

🛠️ Requirements

Minimal Dependencies

Python: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
aiohttp: >= 3.8.0

That's it! No complex dependencies.

🤝 Contributing

Contributions are welcome and appreciated.

Quick Start

Fork this repository
Create a branch (git checkout -b feature/your-change)
Make your changes and test locally
Commit with a clear message
Open a Pull Request

Not sure where to start?

Found a bug? Open an issue: GitHub Issues
Have a feature idea? Share it in GitHub Issues
Want to improve docs or examples? PRs are always welcome

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔖 Credits & Acknowledgments

Special thanks to alexmercerind for youtube-search-python
Special thanks to aiohttp
Crafted with passion by CertifiedCoders
Special thanks to all contributors and users of ytlookup

FilesExpand file tree

README.md

Latest commit

History