# Search

Search authors, works and topics.

Canonical: https://interlinea.aeterna-institute.org/docs/api/search

`GET /api/v1/search`

Authors and works whose names or titles match, accent-insensitive, best known first. A query that names a topic (war, love, the gods, friendship, death, rhetoric, letters, comedy, …) also returns hand-picked works for it. An empty query lists works by rank.

## Parameters

| Field | Type | Description |
|---|---|---|
| `q` | string, in query | Optional. Words from a name or title, in English, Latin or Greek. Default `""`. Up to 200 characters. Example `aeneid`. |
| `lang` | string, in query | Optional. Only this language. One of `la`, `grc`, `latin`, `greek`. |
| `limit` | integer, in query | Optional. At most 100. Default `20`. From 1 to 100. |
| `offset` | integer, in query | Optional. Default `0`. From 0 to 100,000. |

## Response

`200 OK` with a `SearchResult` object.

| Field | Type | Description |
|---|---|---|
| `query` | string |  |
| `lang` | string or null | Language code: la (Latin) or grc (Ancient Greek). One of `la`, `grc`. |
| `total` | integer | Matching works. |
| `offset` | integer |  |
| `limit` | integer |  |
| `next` | string or null | The next page of works. |
| `topics` | array of object | Hand-picked works for a topic the query names (war, love, the gods, …). |
| `topics[].key` | string |  |
| `topics[].label` | string |  |
| `topics[].blurb` | string |  |
| `topics[].works` | array of WorkSummary |  |
| `topics[].works[].title` | string |  |
| `topics[].works[].nativeTitle` | string or null | The title in Latin or Greek, when it differs. |
| `topics[].works[].author` | string |  |
| `topics[].works[].lang` | string | Language code: la (Latin) or grc (Ancient Greek). One of `la`, `grc`. |
| `topics[].works[].genre` | string or null |  |
| `topics[].works[].words` | integer |  |
| `topics[].works[].sections` | integer | Reading sections. |
| `topics[].works[].urn` | string or null | CTS URN, e.g. urn:cts:latinLit:phi0690.phi003.perseus-lat2:1.1-1.11. Null when the edition has none (The Latin Library's own numbering). |
| `topics[].works[].url` | string | Absolute URL. |
| `topics[].works[].api` | string | Absolute URL. |
| `authors` | array of AuthorSummary |  |
| `authors[].name` | string |  |
| `authors[].nativeName` | string or null |  |
| `authors[].lang` | string | Language code: la (Latin) or grc (Ancient Greek). One of `la`, `grc`. |
| `authors[].period` | string or null |  |
| `authors[].url` | string | Absolute URL. |
| `authors[].api` | string | Absolute URL. |
| `works` | array of WorkSummary |  |
| `works[].title` | string |  |
| `works[].nativeTitle` | string or null | The title in Latin or Greek, when it differs. |
| `works[].author` | string |  |
| `works[].lang` | string | Language code: la (Latin) or grc (Ancient Greek). One of `la`, `grc`. |
| `works[].genre` | string or null |  |
| `works[].words` | integer |  |
| `works[].sections` | integer | Reading sections. |
| `works[].urn` | string or null | CTS URN, e.g. urn:cts:latinLit:phi0690.phi003.perseus-lat2:1.1-1.11. Null when the edition has none (The Latin Library's own numbering). |
| `works[].url` | string | Absolute URL. |
| `works[].api` | string | Absolute URL. |

## Errors

| Status | When |
|---|---|
| `400 Bad Request` | A parameter is missing or invalid, or the reference isn't a text. |
| `429 Too Many Requests` | Too many requests from one address. Wait a minute. |
| `500 Internal Server Error` | Something went wrong on our side. |

Error bodies are described in [Caching, limits and errors](https://interlinea.aeterna-institute.org/docs/limits.md#errors).

## Example request

curl:

```sh
curl "https://interlinea.aeterna-institute.org/api/v1/search?q=aeneid"
```

JavaScript:

```js
const res = await fetch("https://interlinea.aeterna-institute.org/api/v1/search?q=aeneid")
const data = await res.json()
console.log(data)
```

Python:

```python
import json
from urllib.request import urlopen

with urlopen("https://interlinea.aeterna-institute.org/api/v1/search?q=aeneid") as res:
    data = json.load(res)

print(data)
```

## Example response

Response (200 OK):

```json
{
  "query": "aeneid",
  "lang": null,
  "total": 4,
  "offset": 0,
  "limit": 20,
  "next": null,
  "topics": [],
  "authors": [
    {
      "name": "Vergil's Aeneid II",
      "nativeName": null,
      "lang": "la",
      "period": "late-republic-augustan",
      "url": "https://interlinea.aeterna-institute.org/library/latin/vergil-s-aeneid-ii",
      "api": "https://interlinea.aeterna-institute.org/api/v1/library/latin/vergil-s-aeneid-ii"
    }
  ],
  "works": [
    {
      "title": "Aeneid",
      "nativeTitle": null,
      "author": "Vergil's Aeneid II",
      "lang": "la",
      "genre": "epic",
      "words": 5172,
      "sections": 19,
      "urn": null,
      "url": "https://interlinea.aeterna-institute.org/library/latin/vergil-s-aeneid-ii/aeneid",
      "api": "https://interlinea.aeterna-institute.org/api/v1/library/latin/vergil-s-aeneid-ii/aeneid"
    },
    {
      "title": "Aeneid",
      "nativeTitle": "Aeneis",
      "author": "Virgil",
      "lang": "la",
      "genre": "epic",
      "words": 63347,
      "sections": 223,
      "urn": "urn:cts:latinLit:phi0690.phi003",
      "url": "https://interlinea.aeterna-institute.org/library/latin/virgil/aeneid",
      "api": "https://interlinea.aeterna-institute.org/api/v1/library/latin/virgil/aeneid"
    },
    {
      "title": "Selections from The Aeneid (19 B.C.)",
      "nativeTitle": null,
      "author": "Imperialisms, Ancient and Modern",
      "lang": "la",
      "genre": null,
      "words": 284,
      "sections": 1,
      "urn": null,
      "url": "https://interlinea.aeterna-institute.org/library/latin/imperialisms-ancient-and-modern/selections-from-the-aeneid-19-b-c",
      "api": "https://interlinea.aeterna-institute.org/api/v1/library/latin/imperialisms-ancient-and-modern/selections-from-the-aeneid-19-b-c"
    },
    // 1 more
  ]
}
```

## Try it

Send a real GET from your browser and see the answer, its status and how long it took.

---

Previous: [Words](https://interlinea.aeterna-institute.org/docs/api/words.md)
Next: [Author](https://interlinea.aeterna-institute.org/docs/api/author.md)