Semantic Art Search in Python: Find Artworks by Mood, Subject or Style
Keyword search finds artworks whose titles contain your words. Semantic search finds artworks that match what you mean: "a calm harbour at sunset", "a melancholy portrait in blue tones", "a lone figure seen from behind". This tutorial uses Python and the requests library to run natural-language searches against the Art Search API, add filters, page through results and handle quota and rate-limit errors.
What you need
- Python 3 and the requests library:
pip install requests. - A free API key from the console. The free plan includes 50 requests a day, at up to 60 requests per minute, for non-commercial projects.
- The key in an environment variable, so it stays out of your code:
export ARTSEARCH_API_KEY=your-key Your first semantic search
The Search Artworks endpoint is GET https://api.artsearch.io/artworks. Send the key in the x-api-key header (or as the api-key query parameter) and describe what you're looking for in query:
import os
import requests
response = requests.get(
"https://api.artsearch.io/artworks",
params={"query": "a calm harbour at sunset", "number": 5},
headers={"x-api-key": os.environ["ARTSEARCH_API_KEY"]},
timeout=30,
)
response.raise_for_status()
data = response.json()
print(data["available"], "matching artworks")
for artwork in data["artworks"]:
print(artwork["id"], artwork["title"], artwork["image"])
# Every response reports your quota
print(response.headers["X-API-Quota-Request"], "request(s) used by this call")
print(response.headers["X-API-Quota-Used"], "used today")
print(response.headers["X-API-Quota-Left"], "left today") The response has four fields. This is the example from the documentation for query=medieval knights and number=3:
{
"available": 993,
"number": 3,
"offset": 0,
"artworks": [
{"id": 25623857, "title": "Knightly Sword", "image": "https://img.artsearch.io/artworks/knightly_sword_unknown23_1450.jpg"},
{"id": 25426886, "title": "Sculpture of a Kneeling Knight or King", "image": "https://img.artsearch.io/artworks/sculpture_of_a_kneeling_knight_or_king_unknown383_1250.jpg"},
{"id": 25934005, "title": "A Knight in Armor", "image": "https://img.artsearch.io/artworks/a_knight_in_armor_unknown32_1907.jpg"}
]
} available: how many results the query has.numberandoffset: how many results this page holds and where it starts.artworks: the results, each withid,titleand animageURL.
Writing queries by mood, subject or style
The query is matched against what an artwork shows and evokes, so write it the way you would describe the picture to a person. A query can be up to 300 characters.
| You want | Example query |
|---|---|
| A mood | calm and peaceful lake in the morning mist |
| A subject | a dog sleeping in front of a fireplace |
| A style | impressionist river landscape with boats |
| A composition | a lone figure seen from behind, looking at the sea |
| An object | medieval knights in armour |
Two tips:
- Use filters for hard rules. The query narrows and ranks results by meaning ("medieval knights" matches about a thousand works, not the whole collection), but it is not a strict rule. If you need paintings only, or works from before 1850, use the filters below.
- Names rank, they don't filter. There is no artist parameter and no artist field in the response. An artist's name in the query ranks related works first, which can include followers and similar styles.
Filters
All filters are optional query parameters and can be combined with each other and with query:
| Parameter | Meaning | Example |
|---|---|---|
earliest-start-date | Created after this year | 1750 |
latest-start-date | Created before this year | 1755 |
earliest-end-date | For works made over a period: completed after this year | 1751 |
latest-end-date | Completed before this year | 1760 |
type | Artwork type, such as painting, drawing, print, sculpture, photograph | painting |
material | Material, such as oil_paint, canvas, ink, bronze, ivory | ivory |
technique | Technique, such as etching, woodcut, lithography, engraving | etching |
origin | Country or region of origin | Italy |
min-ratio, max-ratio | Image aspect ratio (width / height), 0 to 10 | 0.8, 1.5 |
type, material and technique take values from fixed lists; the endpoint documentation has all of them. The aspect-ratio filters help when results must fit a layout: min-ratio=1.2 returns images that are wider than tall.
The complete script further down has a helper, search_artworks(), that takes filters as Python keyword arguments and turns earliest_start_date into earliest-start-date:
from art_search import search_artworks
page = search_artworks(
"a lone figure seen from behind, looking at the sea",
number=10,
type="painting",
earliest_start_date=1800,
latest_start_date=1850,
min_ratio=1.2, # wider than tall
)
for artwork in page["artworks"]:
print(artwork["title"]) Pagination with offset and number
One request returns up to 10 artworks (number from 1 to 10). To get more, raise offset, which accepts 0 to 1,000, so a query can return at most 1,010 results. Every page costs one request from your daily quota, so fetch only as many pages as you show.
The iter_artworks() generator in the script below handles this. It stops when it has enough results, when the API has no more (available), or at the offset limit, and it waits one second between pages to stay within the free plan's rate limit. The Retrieve Artwork endpoint adds the dates and a description for any result:
from art_search import get_artwork, iter_artworks
for artwork in iter_artworks("still life with flowers and insects", limit=30, type="painting"):
print(artwork["id"], artwork["title"])
details = get_artwork(25623857)
print(details["start_date"], details["end_date"])
print(details["description"].split("\n")[0]) Thirty results cost three requests, and the details call costs one more.
Handling 401, 402 and 429
| Status | Meaning | What to do |
|---|---|---|
| 401 | The API key is missing or wrong. | Check ARTSEARCH_API_KEY. Don't retry. |
| 402 | On the free plan, the daily quota is used up. | Stop until the quota resets at midnight UTC, or upgrade. Paid plans continue at a per-request price instead. |
| 429 | Too many requests per second or too many at once. | Wait and retry. Use Retry-After if the response has it, otherwise back off exponentially. |
The rate limits depend on the plan: free 60 per minute and 1 at a time, Apprentice 2 per second, Artisan 10 per second and Maestro 20 per second (rate limits and quotas, pricing). Each response also carries three headers you can log or show in an admin page: X-API-Quota-Request (requests used by this call), X-API-Quota-Used (used today) and X-API-Quota-Left (left today), as the first example prints.
The complete script
Save this as art_search.py. It works as a command-line tool and as a module that the snippets above import:
"""Semantic art search with the Art Search API.
Usage:
export ARTSEARCH_API_KEY=your-key
python art_search.py "quiet winter landscape at dusk" --type painting --from 1800 --to 1900
"""
import argparse
import os
import time
import requests
API_URL = "https://api.artsearch.io"
MAX_OFFSET = 1000 # the API accepts offset 0 to 1000
MAX_NUMBER = 10 # and number 1 to 10 per request
class QuotaExceeded(Exception):
"""HTTP 402: the daily quota is used up. It resets at midnight UTC."""
session = requests.Session()
session.headers["x-api-key"] = os.environ["ARTSEARCH_API_KEY"]
def retry_delay(response, attempt):
"""Seconds to wait after a 429: Retry-After if the response has it, else 1, 2, 4... seconds."""
try:
return float(response.headers["Retry-After"])
except (KeyError, ValueError):
return 2 ** attempt
def call(path, params=None, retries=3):
"""GET an Art Search endpoint and return the parsed JSON."""
for attempt in range(retries + 1):
response = session.get(API_URL + path, params=params, timeout=30)
if response.status_code == 429 and attempt < retries:
time.sleep(retry_delay(response, attempt))
continue
if response.status_code == 402:
raise QuotaExceeded("The daily quota is used up. It resets at midnight UTC.")
response.raise_for_status() # 401 (bad key), 429 after all retries, 5xx
return response.json()
def search_artworks(query=None, number=10, offset=0, **filters):
"""Return one page of results.
Filters use Python names: earliest_start_date=1800 is sent as earliest-start-date.
Filters set to None are left out.
"""
# Always send a query, empty for a filter-only search.
params = {"query": query or "", "number": number, "offset": offset}
for name, value in filters.items():
if value is not None:
params[name.replace("_", "-")] = value
return call("/artworks", params)
def iter_artworks(query=None, limit=30, **filters):
"""Yield up to `limit` artworks, one page (one request) at a time."""
offset = 0
while offset < limit and offset <= MAX_OFFSET:
page = search_artworks(query, number=min(MAX_NUMBER, limit - offset), offset=offset, **filters)
yield from page["artworks"]
offset += len(page["artworks"])
if not page["artworks"] or offset >= page["available"]:
return
time.sleep(1) # stays well under the Free plan's 60 requests per minute
def get_artwork(artwork_id):
"""Title, image, start_date, end_date and description of one artwork."""
return call(f"/artworks/{artwork_id}")
def main():
parser = argparse.ArgumentParser(description="Find artworks by mood, subject or style.")
parser.add_argument("query", help='for example "melancholy portrait in blue tones"')
parser.add_argument("--type", help="painting, drawing, print, sculpture, photograph, ...")
parser.add_argument("--from", dest="start", type=int, help="created after this year (earliest-start-date)")
parser.add_argument("--to", dest="end", type=int, help="created before this year (latest-start-date)")
parser.add_argument("--origin", help="country or region of origin, for example Japan")
parser.add_argument("--limit", type=int, default=20, help="how many results to print")
args = parser.parse_args()
results = iter_artworks(
args.query,
limit=args.limit,
type=args.type,
earliest_start_date=args.start,
latest_start_date=args.end,
origin=args.origin,
)
try:
for artwork in results:
print(f"{artwork['id']} {artwork['title']}\n {artwork['image']}")
except QuotaExceeded as error:
print(error)
if __name__ == "__main__":
main() Run it with a description and any filters:
python art_search.py "quiet winter landscape at dusk" --type painting --from 1800 --to 1900
python art_search.py "woodblock print of a wave" --origin Japan --limit 10
python art_search.py "medieval knights" --limit 3 Each result prints as its id and title, with the image URL on the next line. For the documentation's example query, the last command prints output like this:
25623857 Knightly Sword
https://img.artsearch.io/artworks/knightly_sword_unknown23_1450.jpg
25426886 Sculpture of a Kneeling Knight or King
https://img.artsearch.io/artworks/sculpture_of_a_kneeling_knight_or_king_unknown383_1250.jpg
25934005 A Knight in Armor
https://img.artsearch.io/artworks/a_knight_in_armor_unknown32_1907.jpg A few notes on the design:
- One
requests.Sessionreuses the connection and sends the key on every call. call()retries 429 responses up to three times and turns 402 into aQuotaExceededexception, so your code can stop cleanly when the day's quota is gone.- Filters set to
Noneare left out of the request, which keeps the command-line options simple.
Next steps
- Prefer a client library? The SDKs page lists one for Python and 20 other languages.
- Show a daily painting on a website: build a painting of the day widget.
- Get one random artwork per call with the Random Artwork endpoint, or try the random artwork generator.
- Compare Art Search with the free museum APIs: the best art and museum APIs.