Semantic Art Search in Python: Find Artworks by Mood, Subject or Style

Last updated · Art Search

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

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.
  • number and offset: how many results this page holds and where it starts.
  • artworks: the results, each with id, title and an image URL.

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 wantExample query
A moodcalm and peaceful lake in the morning mist
A subjecta dog sleeping in front of a fireplace
A styleimpressionist river landscape with boats
A compositiona lone figure seen from behind, looking at the sea
An objectmedieval 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:

ParameterMeaningExample
earliest-start-dateCreated after this year1750
latest-start-dateCreated before this year1755
earliest-end-dateFor works made over a period: completed after this year1751
latest-end-dateCompleted before this year1760
typeArtwork type, such as painting, drawing, print, sculpture, photographpainting
materialMaterial, such as oil_paint, canvas, ink, bronze, ivoryivory
techniqueTechnique, such as etching, woodcut, lithography, engravingetching
originCountry or region of originItaly
min-ratio, max-ratioImage aspect ratio (width / height), 0 to 100.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

StatusMeaningWhat to do
401The API key is missing or wrong.Check ARTSEARCH_API_KEY. Don't retry.
402On 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.
429Too 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.Session reuses the connection and sends the key on every call.
  • call() retries 429 responses up to three times and turns 402 into a QuotaExceeded exception, so your code can stop cleanly when the day's quota is gone.
  • Filters set to None are left out of the request, which keeps the command-line options simple.

Next steps