0
# Image Search
1

2
Searches for images using DuckDuckGo's image search with comprehensive filtering options including size, color, type, layout, and licensing filters, returning detailed metadata for each result.
3

4
## Capabilities
5

6
### Image Search Function
7

8
Searches for images using specified keywords with extensive filtering and configuration options.
9

10
```python { .api }
11
def images(
12
    keywords: str,
13
    region: str = "us-en",
14
    safesearch: str = "moderate",
15
    timelimit: str | None = None,
16
    size: str | None = None,
17
    color: str | None = None,
18
    type_image: str | None = None,
19
    layout: str | None = None,
20
    license_image: str | None = None,
21
    max_results: int | None = None,
22
) -> list[dict[str, str]]:
23
    """
24
    DuckDuckGo images search. Query params: https://duckduckgo.com/params.
25

26
    Parameters:
27
    - keywords (str): Search keywords/query terms
28
    - region (str): Region code (us-en, uk-en, ru-ru, etc.). Defaults to "us-en".
29
    - safesearch (str): Safety filter level ("on", "moderate", "off"). Defaults to "moderate".
30
    - timelimit (str, optional): Time filter ("Day", "Week", "Month", "Year"). Defaults to None.
31
    - size (str, optional): Image size filter ("Small", "Medium", "Large", "Wallpaper"). Defaults to None.
32
    - color (str, optional): Color filter ("color", "Monochrome", "Red", "Orange", "Yellow", "Green", "Blue", "Purple", "Pink", "Brown", "Black", "Gray", "Teal", "White"). Defaults to None.
33
    - type_image (str, optional): Image type filter ("photo", "clipart", "gif", "transparent", "line"). Defaults to None.
34
    - layout (str, optional): Layout filter ("Square", "Tall", "Wide"). Defaults to None.
35
    - license_image (str, optional): License filter ("any", "Public", "Share", "ShareCommercially", "Modify", "ModifyCommercially"). Defaults to None.
36
    - max_results (int, optional): Maximum number of results to return. If None, returns results from first response only. Defaults to None.
37

38
    Returns:
39
    List of dictionaries with image search results containing:
40
    - "title" (str): Image title/description
41
    - "image" (str): Direct image URL
42
    - "thumbnail" (str): Thumbnail image URL
43
    - "url" (str): Source webpage URL
44
    - "height" (int): Image height in pixels
45
    - "width" (int): Image width in pixels  
46
    - "source" (str): Source domain/website name
47

48
    Raises:
49
    - DuckDuckGoSearchException: Base exception for search errors
50
    - RatelimitException: API request rate limit exceeded
51
    - TimeoutException: Request timeout occurred
52
    """
53
```
54

55
### Usage Examples
56

57
Basic image search:
58

59
```python
60
from duckduckgo_search import DDGS
61

62
with DDGS() as ddgs:
63
    images = ddgs.images("cats")
64
    for image in images:
65
        print(f"Title: {image['title']}")
66
        print(f"Image URL: {image['image']}")
67
        print(f"Source: {image['url']}")
68
        print(f"Size: {image['width']}x{image['height']}")
69
        print("---")
70
```
71

72
Image search with filters:
73

74
```python
75
from duckduckgo_search import DDGS
76

77
with DDGS() as ddgs:
78
    # Search for large, recent photos with specific color
79
    images = ddgs.images(
80
        keywords="mountain landscape",
81
        region="us-en",
82
        safesearch="moderate",
83
        timelimit="Month",  # Past month
84
        size="Large",
85
        color="Green", 
86
        type_image="photo",
87
        layout="Wide",
88
        max_results=20
89
    )
90
    
91
    for image in images:
92
        print(f"Title: {image['title']}")
93
        print(f"Dimensions: {image['width']}x{image['height']}")
94
        print(f"Source: {image['source']}")
95
        print(f"Image: {image['image']}")
96
        print("---")
97
```
98

99
Image search with Creative Commons licensing:
100

101
```python
102
from duckduckgo_search import DDGS
103

104
with DDGS() as ddgs:
105
    # Search for images with commercial usage rights
106
    images = ddgs.images(
107
        keywords="business meeting",
108
        license_image="ModifyCommercially",  # Free to modify, share, and use commercially
109
        type_image="photo",
110
        size="Large",
111
        max_results=15
112
    )
113
    
114
    for image in images:
115
        print(f"Title: {image['title']}")
116
        print(f"License: Free to modify, share, and use commercially")
117
        print(f"Image URL: {image['image']}")
118
        print(f"Source: {image['url']}")
119
        print("---")
120
```
121

122
Download images with metadata:
123

124
```python
125
from duckduckgo_search import DDGS
126
import requests
127
from pathlib import Path
128

129
def download_image(image_data, folder="images"):
130
    """Download image with metadata"""
131
    Path(folder).mkdir(exist_ok=True)
132
    
133
    try:
134
        response = requests.get(image_data['image'], timeout=10)
135
        if response.status_code == 200:
136
            # Create filename from title and dimensions
137
            safe_title = "".join(c for c in image_data['title'][:50] if c.isalnum() or c in (' ', '_')).rstrip()
138
            filename = f"{safe_title}_{image_data['width']}x{image_data['height']}.jpg"
139
            filepath = Path(folder) / filename
140
            
141
            with open(filepath, 'wb') as f:
142
                f.write(response.content)
143
            
144
            print(f"Downloaded: {filename}")
145
            return str(filepath)
146
    except Exception as e:
147
        print(f"Failed to download {image_data['title']}: {e}")
148
    
149
    return None
150

151
with DDGS() as ddgs:
152
    images = ddgs.images("nature photography", max_results=5)
153
    
154
    for image in images:
155
        print(f"Processing: {image['title']}")
156
        downloaded_path = download_image(image)
157
        if downloaded_path:
158
            print(f"Saved to: {downloaded_path}")
159
```
160

161
### Error Handling
162

163
Handle image search errors:
164

165
```python
166
from duckduckgo_search import DDGS
167
from duckduckgo_search.exceptions import (
168
    DuckDuckGoSearchException,
169
    RatelimitException,
170
    TimeoutException
171
)
172

173
try:
174
    with DDGS() as ddgs:
175
        images = ddgs.images("test query", max_results=100)
176
        print(f"Retrieved {len(images)} images")
177
        
178
        for image in images:
179
            # Validate image data
180
            required_fields = ['title', 'image', 'thumbnail', 'url', 'height', 'width', 'source']
181
            if all(field in image for field in required_fields):
182
                print(f"Valid image: {image['title']} ({image['width']}x{image['height']})")
183
            else:
184
                print(f"Incomplete image data: {image}")
185
                
186
except RatelimitException as e:
187
    print(f"Rate limit exceeded: {e}")
188
    
189
except TimeoutException as e:
190
    print(f"Request timed out: {e}")
191
    
192
except DuckDuckGoSearchException as e:
193
    print(f"Image search error: {e}")
194
```
195

196
## Parameter Details
197

198
### Size Options
199
- `"Small"`: Small images
200
- `"Medium"`: Medium-sized images  
201
- `"Large"`: Large images
202
- `"Wallpaper"`: Wallpaper-sized images (typically high resolution)
203

204
### Color Options  
205
- `"color"`: All colors
206
- `"Monochrome"`: Black and white images
207
- `"Red"`, `"Orange"`, `"Yellow"`: Specific color filters
208
- `"Green"`, `"Blue"`, `"Purple"`: Specific color filters  
209
- `"Pink"`, `"Brown"`, `"Black"`: Specific color filters
210
- `"Gray"`, `"Teal"`, `"White"`: Specific color filters
211

212
### Type Options
213
- `"photo"`: Photographic images
214
- `"clipart"`: Clip art and illustrations
215
- `"gif"`: Animated GIF images
216
- `"transparent"`: Images with transparent backgrounds
217
- `"line"`: Line drawings and sketches
218

219
### Layout Options
220
- `"Square"`: Square aspect ratio images
221
- `"Tall"`: Portrait orientation (taller than wide)
222
- `"Wide"`: Landscape orientation (wider than tall)
223

224
### License Options
225
- `"any"`: All Creative Commons licenses
226
- `"Public"`: Public Domain (no restrictions)
227
- `"Share"`: Free to Share and Use
228
- `"ShareCommercially"`: Free to Share and Use Commercially  
229
- `"Modify"`: Free to Modify, Share, and Use
230
- `"ModifyCommercially"`: Free to Modify, Share, and Use Commercially
231

232
### Time Limits
233
- `"Day"`: Past day
234
- `"Week"`: Past week
235
- `"Month"`: Past month  
236
- `"Year"`: Past year
237

238
### SafeSearch Options
239
- `"on"`: Strict filtering, blocks adult content
240
- `"moderate"`: Moderate filtering (default)
241
- `"off"`: No filtering