Usage guide

Searching with AO3 OPDS

Every OPDS client that supports search gets it automatically: the catalog publishes an OpenSearch description, and the reader uses it to know where to send your queries and how to render the results.

How it works

1. 1

   The catalog advertises a search endpoint

   Every catalog response (both /opds/v1 and /opds/v2) includes a link with rel="search" pointing to anapplication/opensearchdescription+xml document:

   https://ao3-opds.abelmuak.com/opds/opensearch.xml

2. 2

   The reader fetches that file

   The OpenSearch description lists one <Url> per format the catalog supports: OPDS 1.2 (Atom/XML) and OPDS 2.0 (JSON). The reader picks the one it understands and shows a search box for that catalog.

3. 3

   Your query hits the search URL

   When you type a query and submit it, the reader sends a GET to the search URL with your terms in the q parameter (and, for paginated clients, thepage number). For example:

   https://ao3-opds.abelmuak.com/opds/search/v1?q=fandom%3A%22Harry%20Potter%22&page=1

4. 4

   You get back a regular OPDS feed

   The response is a standard OPDS catalog of search results, with the same acquisition links as the main feed, so you can browse, paginate and download epubs exactly as you would for recent works.

Searching in your reader

The exact UX depends on your reader, but the general flow is the same in every OPDS client that supports search (KOReader, Thorium Reader, Calibre with the OPDS Client plugin, etc.).

1. 1

   Open the AO3 catalog

   From the catalogs list in your reader, open the AO3 catalog you added.

2. 2

   Find the search field

   Look for a search bar, a magnifier icon, or a "Search this catalog" option. If your reader shows a search button at the catalog level, the OpenSearch description has been picked up correctly.

3. 3

   Type a query and submit

   You can use plain words (a title, an author name, a tag...) or AO3's native search fields — see the cheat sheet below. The reader sends it to the right search URL automatically and renders the results as another browsable catalog.

4. 4

   Browse the results

   Results are paginated the same way recent works are: open an entry to see its details and download the epub, or use the "next page" link to see more.

AO3 search syntax cheat sheet

Queries are forwarded straight to AO3's own search, so you can use its full field syntax. A few of the most useful ones:

By field

Prefix the field name with field: (or wrap the value in quotes for multi-word values).

Combining terms

Combine terms with AND / OR / NOT (or && / || / !!), and group with parentheses.

Rating and category

Use the same letters AO3 uses on its filters.

Sorting

The OPDS feed lists results in the order AO3 returns them, which is the same order its web search would show. Sorting options are not exposed through OPDS today — use the web UI to refine the query, then copy the equivalent field syntax into the OPDS search bar.

URL reference

The two search endpoints described in the OpenSearch document are:

Parameters:

• q — the search terms. Use AO3 field syntax for precise filters. Required.
• page — 1-based page number for paginated results. Defaults to 1 if omitted.