Wikimedia APIcommons.wikimedia.org ↗
Search freely licensed images and media on Wikimedia Commons. Get file URLs, thumbnail links, license codes, and attribution metadata via one API endpoint.
What is the Wikimedia API?
The Wikimedia Commons API exposes one endpoint — search_images — that returns up to 50 file records per call matching any free-text query against Commons' catalog of over 100 million freely licensed media files. Each record includes the file title, caption, thumbnail URL, original file URL, dimensions, MIME type, license code, and attribution fields, giving you everything needed to legally display or cite a media file.
curl -X GET 'https://api.parse.bot/scraper/6ca6a342-b9ff-4266-8b95-6f289aa482ee/search_images?query=Athens+city+center+night&image_type=photo' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace commons-wikimedia-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Wikimedia Commons image search — bounded, re-runnable."""
from parse_apis.commons_wikimedia_org_api import WikimediaCommons, ImageType, InputFormatInvalid
client = WikimediaCommons()
# Search for freely licensed images, capping total items fetched.
for image in client.images.search(query="Athens city center night", limit=5):
print(image.title, f"{image.width}x{image.height}", image.license)
# Drill into the first result for a different query.
image = client.images.search(query="solar eclipse 2024", image_type=ImageType.PHOTO, limit=1).first()
if image is not None:
print(image.title)
print(" Original:", image.original_url)
print(" Thumbnail:", image.thumbnail_url)
print(" Artist:", image.artist)
print(" Attribution required:", image.attribution_required)
if image.license_url is not None:
print(" License:", image.license, image.license_url)
print(" Categories:", ", ".join(image.categories))
# Demonstrate typed error handling for a malformed request.
try:
client.images.search(query="", limit=1).first()
except InputFormatInvalid as e:
print("Caught expected error:", e.message)
print("exercised: images.search")
Searches Wikimedia Commons files by free-text query and returns one record per matching file in the site's relevance order, with the file title, caption (the file's description with markup stripped), a thumbnail URL (up to 1200px wide; the site may serve a different size), the original file URL, dimensions, MIME type, license short name/code/URL, attribution flag, artist, credit, original date and categories. All Commons files are freely reusable; the license fields say under which terms (license_url is null for public-domain files). One site request per call. Pagination: limit (1-50) sets records per call, offset is a zero-based position into the result stream; has_more and next_offset describe the continuation. By default only bitmap photographs/images are returned; image_type=any also includes PDFs and other document files. An empty images array is a valid result for a query with no matches. Caption and date_original can be null when the file carries no description or date.
| Param | Type | Description |
|---|---|---|
| limit | integer | Number of records to return per call, clamped to 50. |
| queryrequired | string | Free-text search terms matched against file names, descriptions and categories, e.g. 'Athens city center night'. |
| offset | integer | Zero-based position in the result stream to start from; pass next_offset from a previous call to continue. |
| image_type | string | Which file kinds to include. photo restricts results to bitmap images (photographs); any includes every file type Commons holds. |
{
"type": "object",
"fields": {
"limit": "records requested (after clamping)",
"query": "echo of the search terms",
"images": "array of file records: page_id, title, page_url, caption, thumbnail_url, original_url, width, height, mime, license, license_code, license_url, attribution_required, artist, credit, date_original, categories",
"offset": "offset this call started at",
"has_more": "boolean, true when more results exist",
"next_offset": "offset for the next page, null when exhausted"
},
"sample": {
"data": {
"limit": 3,
"query": "Athens city center night",
"images": [
{
"mime": "image/jpeg",
"title": "File:The Late Roman Wall of Athens at night on May 1, 2024.jpg",
"width": 4000,
"artist": "George E. Koronaios",
"credit": "Own work",
"height": 6000,
"caption": "The remains of the Late Roman Wall of Athens (foreground / left) at night. It is located at the archaeological site of the Areopagus which back in the antiquity was part of the Ancient Agora.",
"license": "CC BY-SA 4.0",
"page_id": 147948888,
"page_url": "https://commons.wikimedia.org/wiki/File:The_Late_Roman_Wall_of_Athens_at_night_on_May_1,_2024.jpg",
"categories": [
"Images with annotations",
"Self-published work",
"Late Roman Wall in the Agora of Athens"
],
"license_url": "https://creativecommons.org/licenses/by-sa/4.0",
"license_code": "cc-by-sa-4.0",
"original_url": "https://upload.wikimedia.org/wikipedia/commons/9/98/The_Late_Roman_Wall_of_Athens_at_night_on_May_1%2C_2024.jpg",
"date_original": "2024-05-01 21:26:31",
"thumbnail_url": "https://thumb.wikimedia.org/wikipedia/commons/thumb/9/98/The_Late_Roman_Wall_of_Athens_at_night_on_May_1%2C_2024.jpg/1280px-The_Late_Roman_Wall_of_Athens_at_night_on_May_1%2C_2024.jpg",
"attribution_required": true
}
],
"offset": 0,
"has_more": true,
"next_offset": 3
},
"status": "success"
}
}About the Wikimedia API
What the API Returns
The search_images endpoint accepts a query string matched against file names, descriptions, and categories on Wikimedia Commons. Each matching record in the images array includes page_id, title, page_url, caption (description with wiki markup stripped), thumbnail_url (up to 1200px wide), original_url, width, height, mime, license, license_code, attribution, and credit. Results arrive in the site's relevance order.
Filtering and Pagination
The image_type parameter lets you restrict results to bitmap photographs (photo) or include every file type such as SVGs and audio files (any). The limit parameter is clamped at 50 records per call. Pagination works via offset: pass the next_offset value from one response as the offset in the next call. The has_more boolean tells you when the result stream is exhausted, and next_offset is null at that point.
License and Attribution Fields
Every record carries license, license_code, attribution, and credit fields drawn from the file's structured metadata on Commons. These are the fields you need to comply with Creative Commons and other open license requirements when embedding or redistributing media. MIME type is included so you can distinguish JPEG photographs from PNG diagrams or SVG illustrations before fetching the original.
The Wikimedia API is a managed, monitored endpoint for commons.wikimedia.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when commons.wikimedia.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official commons.wikimedia.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Populate an article or blog post with on-topic freely licensed photographs, using
thumbnail_urlfor display andattributionfor the required credit line. - Build an image search widget that filters to bitmap photos only via
image_type=photoand paginates results withnext_offset. - Audit license compliance by collecting
license_codevalues across a batch of media files used in a content pipeline. - Generate geo or travel content with correctly attributed illustrative images by querying place names and pulling
original_urlfor high-resolution assets. - Feed a dataset of open-license scientific diagrams or charts into a research tool by querying subject terms and filtering by
mimetype. - Display media file metadata — dimensions, MIME type, caption, and credit — in a CMS asset browser backed by Commons search.
- Cross-reference
page_idvalues against Wikipedia article data to associate illustrative images with encyclopedia entries.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Wikimedia Commons have an official developer API?+
What does the `search_images` endpoint return beyond the file URL?+
page_id, title, page_url, caption, thumbnail_url, original_url, width, height, mime, license, license_code, attribution, and credit. That covers the file's identity, its display and source URLs, its pixel dimensions, format, and the license metadata needed for attribution.Can I retrieve metadata for a specific file by its exact Commons file name rather than doing a keyword search?+
search_images endpoint; direct lookup by file name or page_id is not a separate endpoint. You can fork the API on Parse and revise it to add a direct file-lookup endpoint that accepts a title or page ID.Does the API return category listings or file counts per category?+
What is the maximum number of results I can retrieve in one call, and how do I get more?+
limit parameter is clamped at 50 records per call. To retrieve further results, pass the next_offset value from the previous response as the offset parameter in the next request. When has_more is false, the result stream is exhausted and next_offset is null.