tessl/pypi-pycoingecko

Python3 wrapper around the CoinGecko API (V3) enabling access to cryptocurrency market data, prices, exchanges, and NFT information.

—

Pending

Overview

Eval results

Files

Search & Discovery

Name: tessl/pypi-pycoingecko
Author: tessl

Search functionality for cryptocurrencies, categories, markets, and trending data discovery. This module provides comprehensive search capabilities to find and discover cryptocurrencies, exchanges, and trending market data.

Capabilities

General Search

Search across cryptocurrencies, categories, and markets using text queries.

def search(query, **kwargs):
    """
    Search for coins, categories and markets on CoinGecko using text queries.
    
    Parameters:
    - query (str): Search term (coin name, symbol, or category)
    
    Returns:
    dict: Search results containing 'coins', 'exchanges', and 'categories' arrays
    """

Usage Examples:

# Search for Bitcoin-related items
results = cg.search(query='bitcoin')

# Access search results
coins = results['coins']
exchanges = results['exchanges'] 
categories = results['categories']

# Search for Ethereum
eth_results = cg.search(query='ethereum')

# Search for DeFi category
defi_results = cg.search(query='defi')

Search Results Structure:

{
    "coins": [
        {
            "id": "bitcoin",
            "name": "Bitcoin",
            "symbol": "BTC",
            "market_cap_rank": 1,
            "thumb": "https://assets.coingecko.com/coins/images/1/thumb/bitcoin.png",
            "large": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png"
        },
        {
            "id": "bitcoin-cash",
            "name": "Bitcoin Cash", 
            "symbol": "BCH",
            "market_cap_rank": 15,
            "thumb": "https://assets.coingecko.com/coins/images/780/thumb/bitcoin-cash-circle.png",
            "large": "https://assets.coingecko.com/coins/images/780/large/bitcoin-cash-circle.png"
        }
        # ... more matching coins
    ],
    "exchanges": [
        {
            "id": "bitcoin_com",
            "name": "Bitcoin.com Exchange",
            "market_type": "spot",
            "thumb": "https://assets.coingecko.com/markets/images/525/thumb/logo.png",
            "large": "https://assets.coingecko.com/markets/images/525/large/logo.png"
        }
        # ... more matching exchanges
    ],
    "categories": [
        {
            "id": "bitcoin-fork",
            "name": "Bitcoin Fork"
        }
        # ... more matching categories
    ]
}

Trending Search Data

Get the most popular cryptocurrencies based on search activity.

def get_search_trending(**kwargs):
    """
    Get top 7 trending coin searches based on current search activity.
    
    Returns:
    dict: Contains 'coins' array with trending cryptocurrency data and search metadata
    """

Usage Examples:

# Get current trending cryptocurrencies
trending = cg.get_search_trending()

# Access trending coins
trending_coins = trending['coins']
for coin_data in trending_coins:
    coin = coin_data['item']
    name = coin['name']
    symbol = coin['symbol']
    rank = coin['market_cap_rank']
    score = coin_data['score']  # Trending score (0-7)
    print(f"{name} ({symbol}) - Rank: {rank}, Trending Score: {score}")

# Get trending NFTs if available
if 'nfts' in trending:
    trending_nfts = trending['nfts']
    for nft_data in trending_nfts:
        nft = nft_data['item']
        name = nft['name']
        floor_price = nft['floor_price_in_native_currency']

Trending Data Structure:

{
    "coins": [
        {
            "item": {
                "id": "bitcoin",
                "coin_id": 1,
                "name": "Bitcoin",
                "symbol": "BTC",
                "market_cap_rank": 1,
                "thumb": "https://assets.coingecko.com/coins/images/1/thumb/bitcoin.png",
                "small": "https://assets.coingecko.com/coins/images/1/small/bitcoin.png",
                "large": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png",
                "slug": "bitcoin",
                "price_btc": 1.0,
                "score": 0
            }
        },
        {
            "item": {
                "id": "ethereum",
                "coin_id": 279,
                "name": "Ethereum", 
                "symbol": "ETH",
                "market_cap_rank": 2,
                "thumb": "https://assets.coingecko.com/coins/images/279/thumb/ethereum.png",
                "small": "https://assets.coingecko.com/coins/images/279/small/ethereum.png",
                "large": "https://assets.coingecko.com/coins/images/279/large/ethereum.png",
                "slug": "ethereum",
                "price_btc": 0.05789,
                "score": 1
            }
        }
        // ... 5 more trending coins (total of 7)
    ],
    "nfts": [
        {
            "item": {
                "id": "bored-ape-yacht-club",
                "name": "Bored Ape Yacht Club",
                "symbol": "BAYC",
                "thumb": "https://assets.coingecko.com/nft_contracts/images/12/thumb/bored-ape-yacht-club.png",
                "nft_contract_id": 12,
                "native_currency_symbol": "eth",
                "floor_price_in_native_currency": 35.5,
                "floor_price_24h_percentage_change": {
                    "native_currency": -2.1
                }
            }
        }
        // ... more trending NFTs
    ],
    "categories": [
        {
            "item": {
                "id": "layer-1",
                "name": "Layer 1 (L1)",
                "market_cap_1h_change": 0.5,
                "slug": "layer-1"
            }
        }
        // ... more trending categories
    ]
}

Search Query Optimization

Search Query Types

The search function supports various query types:

Coin Names: "Bitcoin", "Ethereum", "Chainlink"
Coin Symbols: "BTC", "ETH", "LINK"
Categories: "DeFi", "Layer 1", "NFT"
Partial Matches: "bit" (matches Bitcoin, Bitcoin Cash, etc.)
Exchange Names: "Binance", "Coinbase"

Search Best Practices

# Exact matches work best
bitcoin_results = cg.search(query='bitcoin')

# Symbols are case-insensitive  
btc_results = cg.search(query='btc')  # Same as 'BTC'

# Partial matching for discovery
defi_results = cg.search(query='defi')

# Category searches
layer1_results = cg.search(query='layer 1')

Search Result Prioritization

Search results are prioritized by:

Exact matches (highest priority)
Market cap ranking (popular coins ranked higher)
String similarity (partial matches)
Trading volume (more active coins ranked higher)

Trending Algorithm

The trending search data reflects:

Search Volume: Current search activity on CoinGecko
Social Mentions: Twitter and social media activity
Price Movement: Recent price changes and volatility
Trading Volume: Increased trading activity
News Events: Major announcements or developments

Trending scores range from 0-7, with 0 being the most trending.

Data Refresh

Search Results: Updated in real-time as new coins/exchanges are added
Trending Data: Refreshed every 10-15 minutes based on current activity
Trending Rankings: Updated continuously throughout the day

Error Handling

Search endpoints handle various scenarios:

try:
    results = cg.search(query='nonexistent')
    if not results['coins'] and not results['exchanges']:
        print("No results found")
except ValueError as e:
    print(f"Search error: {e}")

Common search issues:

Empty queries return error responses
Special characters are automatically handled
Very long queries (>100 characters) may be truncated
Rate limiting applies to frequent searches

Integration with Other Endpoints

Search results provide IDs that can be used with other endpoints:

# Search for a coin
results = cg.search(query='ethereum')
eth_id = results['coins'][0]['id']  # 'ethereum'

# Use the ID to get detailed data
eth_data = cg.get_coin_by_id(id=eth_id)
eth_price = cg.get_price(ids=eth_id, vs_currencies='usd')

# Search for an exchange
exchange_results = cg.search(query='binance')
exchange_id = exchange_results['exchanges'][0]['id']  # 'binance'

# Get exchange data
exchange_data = cg.get_exchanges_by_id(id=exchange_id)

This integration allows for seamless discovery and detailed analysis workflows.

Install with Tessl CLI