Public API Documentation > Resources > Search

Search API

Search for anything on Artsy.

Retrieving Search Results

Search for anything by following the search link from root with a query parameter.

curl -v "https://stagingapi.artsy.net/api/search?q=Andy+Warhol" -H "X-XAPP-Token: XAPP_TOKEN"

The response is a paginated result with embedded search results.

Search Result JSON Format

error: the server responded with status 404

Possible Types

Type Resource
Artist An Artsy artist.
Artwork An Artsy artwork.
Profile An Artsy profile.
Gene An Artsy gene.
Show An Artsy show.

The API will also return search results with a "null" value for "type". Those are not supported by the API (yet) and may include features, posts or shows.

Links

Key Target
self The resource found, when available.
thumbnail Image thumbnail, when available.
permalink An external location on the artsy.net website.

You can follow the "self" link on each individual search result, however because of delays in indexing and content restrictions there's no guarantee that those links will always return a resource. Notably, only a subset of artworks is available via the API, whereas search returns all content published on artsy.net.

Advanced Search

You can leverage the filtering capabilities of Google Custom Search that provides the back-end for the Artsy search API.

For example, only search for artists by specifying an "artist" open-graph type with more:pagemap:metatags-og_type:artist.

curl -v "https://stagingapi.artsy.net/api/search?q=Andy+Warhol+more:pagemap:metatags-og_type:artist" -H "X-XAPP-Token: XAPP_TOKEN"

Spell Check

If the API fails to find any results for a term it will attempt to correct its spelling. The response will be a 302 redirect to the suggested search URL. For example, searching for "Tauba Orbach" will redirect to a search for "Tauba Auerbach".

curl -v "https://stagingapi.artsy.net/api/search?q=Tauba+Orbach" -H "X-XAPP-Token: XAPP_TOKEN"

< HTTP/1.1 302 Found
< Content-Type: application/json
< Location: https://stagingapi.artsy.net/api/api/search?q=Tauba+Auerbach

{
  "_links" : {
    "location" : {
      "href" : "https://stagingapi.artsy.net/api/search?q=Tauba+Auerbach"
    }
  }
}

Public Artworks, Stale and New Content

Search indexing is not immediate. Search results may not always contain content that has been very recently added.

Search results may contain metadata about artworks that are not publicly accessible via the Artsy API or that describe content that has been removed since it was last indexed. Following links for such results may result in a 404 Not Found error.

Example

{
  "total_count": 10000,
  "offset": 0,
  "q": "Andy Warhol",
  "_links": {
    "self": {
      "href": "https://stagingapi.artsy.net/api/search?offset=0&q=Andy+Warhol&size=10"
    },
    "next": {
      "href": "https://stagingapi.artsy.net/api/search?offset=10&q=Andy+Warhol&size=10"
    }
  },
  "_embedded": {
    "results": [
      {
        "type": "artist",
        "title": "Andy Warhol",
        "description": null,
        "og_type": "artist",
        "_links": {
          "self": {
            "href": "https://stagingapi.artsy.net/api/artists/4d8b92b34eb68a1b2c0003f4"
          },
          "permalink": {
            "href": "https://staging.artsy.net/artist/andy-warhol"
          },
          "thumbnail": {
            "href": "https://d32dm0rphc51dk.cloudfront.net/E-k-uLoQADM8AjadsSKHrA/square.jpg"
          }
        }
      },
      {
        "type": "show",
        "title": "Andy Andy Warhol",
        "description": null,
        "og_type": "show",
        "_links": {
          "self": {
            "href": "https://stagingapi.artsy.net/api/shows/63a9af11f67153000dc89c71"
          },
          "permalink": {
            "href": "https://staging.artsy.net/show/elies-fine-art-andy-andy-warhol"
          },
          "thumbnail": {
            "href": "/assets/shared/missing_image.png"
          }
        }
      },
      {
        "type": "show",
        "title": "Andy Warhol",
        "description": null,
        "og_type": "show",
        "_links": {
          "self": {
            "href": "https://stagingapi.artsy.net/api/shows/61ea6a091a0905000c046b02"
          },
          "permalink": {
            "href": "https://staging.artsy.net/show/artificial-gallery-andy-warhol"
          },
          "thumbnail": {
            "href": "https://d32dm0rphc51dk.cloudfront.net/Ps6AG4H0HEw7n-eBfgDGiQ/square.jpg"
          }
        }
      },
      {
        "type": "show",
        "title": "Andy Warhol",
        "description": null,
        "og_type": "show",
        "_links": {
          "self": {
            "href": "https://stagingapi.artsy.net/api/shows/63eba8ad43f618000d3843bd"
          },
          "permalink": {
            "href": "https://staging.artsy.net/show/david-benrimon-fine-art-andy-warhol"
          },
          "thumbnail": {
            "href": "https://d32dm0rphc51dk.cloudfront.net/X4iNKQPT2QgX6xEoO_N5Mw/square.jpg"
          }
        }
      },
      {
        "type": "show",
        "title": "Andy Warhol",
        "description": null,
        "og_type": "show",
        "_links": {
          "self": {
            "href": "https://stagingapi.artsy.net/api/shows/66322d0af9b1cc0011c81a33"
          },
          "permalink": {
            "href": "https://staging.artsy.net/show/lougher-contemporary-andy-warhol"
          },
          "thumbnail": {
            "href": "https://d32dm0rphc51dk.cloudfront.net/Qw0mggraFaGF60CTjZQNwQ/square.jpg"
          }
        }
      },
      {
        "type": "show",
        "title": "Andy Warhol - Photography",
        "description": null,
        "og_type": "show",
        "_links": {
          "self": {
            "href": "https://stagingapi.artsy.net/api/shows/60f0020834cf430012af7609"
          },
          "permalink": {
            "href": "https://staging.artsy.net/show/rudolf-budja-gallery-andy-warhol-photography"
          },
          "thumbnail": {
            "href": "https://d32dm0rphc51dk.cloudfront.net/3HgchcsbSEe9O56fBXM2iA/square.jpg"
          }
        }
      },
      {
        "type": "show",
        "title": "KAWS + Andy Warhol",
        "description": null,
        "og_type": "show",
        "_links": {
          "self": {
            "href": "https://stagingapi.artsy.net/api/shows/667c106a9a8a05000e52be48"
          },
          "permalink": {
            "href": "https://staging.artsy.net/show/hang-up-gallery-kaws-plus-andy-warhol"
          },
          "thumbnail": {
            "href": "https://d32dm0rphc51dk.cloudfront.net/PAf9g3h6vzQN6x3adSAZrQ/square.jpg"
          }
        }
      },
      {
        "type": "show",
        "title": "Highlight: Andy Warhol",
        "description": null,
        "og_type": "show",
        "_links": {
          "self": {
            "href": "https://stagingapi.artsy.net/api/shows/65f89438e17375000dd8ce1a"
          },
          "permalink": {
            "href": "https://staging.artsy.net/show/tanya-baxter-contemporary-highlight-andy-warhol"
          },
          "thumbnail": {
            "href": "https://d32dm0rphc51dk.cloudfront.net/xPGpoM1m_8Kv07TlsUYWZg/square.jpg"
          }
        }
      },
      {
        "type": "show",
        "title": "Andy Warhol Prints",
        "description": null,
        "og_type": "show",
        "_links": {
          "self": {
            "href": "https://stagingapi.artsy.net/api/shows/63f678121d289f000d9c56bc"
          },
          "permalink": {
            "href": "https://staging.artsy.net/show/art-mavens-llc-1-andy-warhol-prints"
          },
          "thumbnail": {
            "href": "https://d32dm0rphc51dk.cloudfront.net/L9BUTGB7M_QU50FhdfSiuA/square.jpg"
          }
        }
      },
      {
        "type": "show",
        "title": "ANDY WARHOL - SUPERSTAR",
        "description": null,
        "og_type": "show",
        "_links": {
          "self": {
            "href": "https://stagingapi.artsy.net/api/shows/63231f672960f8000b8a062e"
          },
          "permalink": {
            "href": "https://staging.artsy.net/show/osme-fine-art-andy-warhol-superstar"
          },
          "thumbnail": {
            "href": "https://d32dm0rphc51dk.cloudfront.net/fFmDLWwujBaI9Dl3xHSKOA/square.jpg"
          }
        }
      }
    ]
  }
}