0
# Search & Discovery
1
2
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.
3
4
## Capabilities
5
6
### General Search
7
8
Search across cryptocurrencies, categories, and markets using text queries.
9
10
```python { .api }
11
def search(query, **kwargs):
12
"""
13
Search for coins, categories and markets on CoinGecko using text queries.
14
15
Parameters:
16
- query (str): Search term (coin name, symbol, or category)
17
18
Returns:
19
dict: Search results containing 'coins', 'exchanges', and 'categories' arrays
20
"""
21
```
22
23
**Usage Examples:**
24
25
```python
26
# Search for Bitcoin-related items
27
results = cg.search(query='bitcoin')
28
29
# Access search results
30
coins = results['coins']
31
exchanges = results['exchanges']
32
categories = results['categories']
33
34
# Search for Ethereum
35
eth_results = cg.search(query='ethereum')
36
37
# Search for DeFi category
38
defi_results = cg.search(query='defi')
39
```
40
41
**Search Results Structure:**
42
43
```python
44
{
45
"coins": [
46
{
47
"id": "bitcoin",
48
"name": "Bitcoin",
49
"symbol": "BTC",
50
"market_cap_rank": 1,
51
"thumb": "https://assets.coingecko.com/coins/images/1/thumb/bitcoin.png",
52
"large": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png"
53
},
54
{
55
"id": "bitcoin-cash",
56
"name": "Bitcoin Cash",
57
"symbol": "BCH",
58
"market_cap_rank": 15,
59
"thumb": "https://assets.coingecko.com/coins/images/780/thumb/bitcoin-cash-circle.png",
60
"large": "https://assets.coingecko.com/coins/images/780/large/bitcoin-cash-circle.png"
61
}
62
# ... more matching coins
63
],
64
"exchanges": [
65
{
66
"id": "bitcoin_com",
67
"name": "Bitcoin.com Exchange",
68
"market_type": "spot",
69
"thumb": "https://assets.coingecko.com/markets/images/525/thumb/logo.png",
70
"large": "https://assets.coingecko.com/markets/images/525/large/logo.png"
71
}
72
# ... more matching exchanges
73
],
74
"categories": [
75
{
76
"id": "bitcoin-fork",
77
"name": "Bitcoin Fork"
78
}
79
# ... more matching categories
80
]
81
}
82
```
83
84
### Trending Search Data
85
86
Get the most popular cryptocurrencies based on search activity.
87
88
```python { .api }
89
def get_search_trending(**kwargs):
90
"""
91
Get top 7 trending coin searches based on current search activity.
92
93
Returns:
94
dict: Contains 'coins' array with trending cryptocurrency data and search metadata
95
"""
96
```
97
98
**Usage Examples:**
99
100
```python
101
# Get current trending cryptocurrencies
102
trending = cg.get_search_trending()
103
104
# Access trending coins
105
trending_coins = trending['coins']
106
for coin_data in trending_coins:
107
coin = coin_data['item']
108
name = coin['name']
109
symbol = coin['symbol']
110
rank = coin['market_cap_rank']
111
score = coin_data['score'] # Trending score (0-7)
112
print(f"{name} ({symbol}) - Rank: {rank}, Trending Score: {score}")
113
114
# Get trending NFTs if available
115
if 'nfts' in trending:
116
trending_nfts = trending['nfts']
117
for nft_data in trending_nfts:
118
nft = nft_data['item']
119
name = nft['name']
120
floor_price = nft['floor_price_in_native_currency']
121
```
122
123
**Trending Data Structure:**
124
125
```python
126
{
127
"coins": [
128
{
129
"item": {
130
"id": "bitcoin",
131
"coin_id": 1,
132
"name": "Bitcoin",
133
"symbol": "BTC",
134
"market_cap_rank": 1,
135
"thumb": "https://assets.coingecko.com/coins/images/1/thumb/bitcoin.png",
136
"small": "https://assets.coingecko.com/coins/images/1/small/bitcoin.png",
137
"large": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png",
138
"slug": "bitcoin",
139
"price_btc": 1.0,
140
"score": 0
141
}
142
},
143
{
144
"item": {
145
"id": "ethereum",
146
"coin_id": 279,
147
"name": "Ethereum",
148
"symbol": "ETH",
149
"market_cap_rank": 2,
150
"thumb": "https://assets.coingecko.com/coins/images/279/thumb/ethereum.png",
151
"small": "https://assets.coingecko.com/coins/images/279/small/ethereum.png",
152
"large": "https://assets.coingecko.com/coins/images/279/large/ethereum.png",
153
"slug": "ethereum",
154
"price_btc": 0.05789,
155
"score": 1
156
}
157
}
158
// ... 5 more trending coins (total of 7)
159
],
160
"nfts": [
161
{
162
"item": {
163
"id": "bored-ape-yacht-club",
164
"name": "Bored Ape Yacht Club",
165
"symbol": "BAYC",
166
"thumb": "https://assets.coingecko.com/nft_contracts/images/12/thumb/bored-ape-yacht-club.png",
167
"nft_contract_id": 12,
168
"native_currency_symbol": "eth",
169
"floor_price_in_native_currency": 35.5,
170
"floor_price_24h_percentage_change": {
171
"native_currency": -2.1
172
}
173
}
174
}
175
// ... more trending NFTs
176
],
177
"categories": [
178
{
179
"item": {
180
"id": "layer-1",
181
"name": "Layer 1 (L1)",
182
"market_cap_1h_change": 0.5,
183
"slug": "layer-1"
184
}
185
}
186
// ... more trending categories
187
]
188
}
189
```
190
191
## Search Query Optimization
192
193
### Search Query Types
194
195
The search function supports various query types:
196
197
1. **Coin Names**: "Bitcoin", "Ethereum", "Chainlink"
198
2. **Coin Symbols**: "BTC", "ETH", "LINK"
199
3. **Categories**: "DeFi", "Layer 1", "NFT"
200
4. **Partial Matches**: "bit" (matches Bitcoin, Bitcoin Cash, etc.)
201
5. **Exchange Names**: "Binance", "Coinbase"
202
203
### Search Best Practices
204
205
```python
206
# Exact matches work best
207
bitcoin_results = cg.search(query='bitcoin')
208
209
# Symbols are case-insensitive
210
btc_results = cg.search(query='btc') # Same as 'BTC'
211
212
# Partial matching for discovery
213
defi_results = cg.search(query='defi')
214
215
# Category searches
216
layer1_results = cg.search(query='layer 1')
217
```
218
219
### Search Result Prioritization
220
221
Search results are prioritized by:
222
1. **Exact matches** (highest priority)
223
2. **Market cap ranking** (popular coins ranked higher)
224
3. **String similarity** (partial matches)
225
4. **Trading volume** (more active coins ranked higher)
226
227
## Trending Algorithm
228
229
The trending search data reflects:
230
- **Search Volume**: Current search activity on CoinGecko
231
- **Social Mentions**: Twitter and social media activity
232
- **Price Movement**: Recent price changes and volatility
233
- **Trading Volume**: Increased trading activity
234
- **News Events**: Major announcements or developments
235
236
Trending scores range from 0-7, with 0 being the most trending.
237
238
## Data Refresh
239
240
- **Search Results**: Updated in real-time as new coins/exchanges are added
241
- **Trending Data**: Refreshed every 10-15 minutes based on current activity
242
- **Trending Rankings**: Updated continuously throughout the day
243
244
## Error Handling
245
246
Search endpoints handle various scenarios:
247
248
```python
249
try:
250
results = cg.search(query='nonexistent')
251
if not results['coins'] and not results['exchanges']:
252
print("No results found")
253
except ValueError as e:
254
print(f"Search error: {e}")
255
```
256
257
Common search issues:
258
- Empty queries return error responses
259
- Special characters are automatically handled
260
- Very long queries (>100 characters) may be truncated
261
- Rate limiting applies to frequent searches
262
263
## Integration with Other Endpoints
264
265
Search results provide IDs that can be used with other endpoints:
266
267
```python
268
# Search for a coin
269
results = cg.search(query='ethereum')
270
eth_id = results['coins'][0]['id'] # 'ethereum'
271
272
# Use the ID to get detailed data
273
eth_data = cg.get_coin_by_id(id=eth_id)
274
eth_price = cg.get_price(ids=eth_id, vs_currencies='usd')
275
276
# Search for an exchange
277
exchange_results = cg.search(query='binance')
278
exchange_id = exchange_results['exchanges'][0]['id'] # 'binance'
279
280
# Get exchange data
281
exchange_data = cg.get_exchanges_by_id(id=exchange_id)
282
```
283
284
This integration allows for seamless discovery and detailed analysis workflows.