Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GuancheData/stage_3/llms.txt

Use this file to discover all available pages before exploring further.

The search endpoint queries the full-text inverted index built from all indexed Gutenberg books. You supply one or more terms in the q parameter and the service returns every book in which all of those terms appear, ranked by how frequently the terms occur across the document. Optional filters let you narrow results by author, language, or publication year. The search service is available directly on port 7003, or through the Nginx reverse proxy on port 8080. For production use, prefer port 8080 so requests are load-balanced across all search nodes.

​
Query parameters

​
q
string
required
One or more space-separated search terms. The query uses AND semantics — every term must appear in a document for it to be included in results. Terms are lowercased and all non-alphanumeric characters are stripped before matching.
​
author
string
Filter results to books whose author field contains this string. The match is case-insensitive and substring-based — austen matches "Austen, Jane".
​
language
string
Filter results to books in the specified language. The match is case-insensitive and substring-based — en matches "en".
​
year
integer
Filter results to books published in exactly this year. Must be a valid integer; an invalid value returns HTTP 400.

​
AND semantics

When you supply multiple space-separated terms in q, only books containing all of the terms are returned. For example, q=whale+sea matches only books where both whale and sea appear — not books that contain only one of the two terms.

​
Sorting and the frequency field

Results are sorted by frequency in descending order by default, meaning books where the query terms appear most often rank first. frequency is the sum of per-term occurrence counts across the document — a book where whale appears 1000 times and sea appears 284 times would have a frequency of 1284. The sort order can be changed to ascending by document ID by setting the SORTING_CRITERIA environment variable on the search service to id.

​
Requests

Basic query: 
curl "http://localhost:8080/search?q=whale+sea"
With filters: 
curl "http://localhost:8080/search?q=love&author=austen&language=en"
Direct access (bypassing Nginx): 
curl "http://localhost:7003/search?q=whale+sea"

​
Response fields

​
status
string
required
"success" on a successful query, "error" when the request is invalid or an internal error occurs.
​
query
string
required
The raw value of the q parameter as supplied in the request.
​
filters
object
required
The filter values applied to this query. Fields are omitted when not supplied.
​
count
integer
required
Total number of matching documents returned.
​
results
array
required
Ordered list of matching books.

​
Response examples

{
  "status": "success",
  "query": "whale sea",
  "filters": {
    "author": null,
    "language": "en",
    "year": null
  },
  "count": 3,
  "results": [
    {
      "id": 2701,
      "title": "Moby-Dick; or, The Whale",
      "author": "Melville, Herman",
      "language": "en",
      "year": 1851,
      "frequency": 1284
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us