Server side search API
You can integrate our server side search in your documentation by using our API.
If you are using Business hosting you will need to replace https://readthedocs.org/ with https://readthedocs.com/ in all the URLs used in the following examples. Check Authentication and authorization if you are using private versions.
API v3
- GET /api/v3/search/
Return a list of search results for a project or subset of projects. Results are divided into sections with highlights of the matching term.
- Query Parameters:
q – Search query (see Search query syntax)
page – Jump to a specific page
page_size – Limits the results per page, default is 50
- Response JSON Object:
type (string) – The type of the result, currently page is the only type.
project (string) – The project object
version (string) – The version object
title (string) – The title of the page
domain (string) – Canonical domain of the resulting page
path (string) – Path to the resulting page
highlights (object) – An object containing a list of substrings with matching terms. Note that the text is HTML escaped with the matching terms inside a
<span>
tag.blocks (object) –
A list of block objects containing search results from the page. Currently, there is one type of block:
section: A page section with a linkable anchor (
id
attribute).
Warning
Except for highlights, any other content is not HTML escaped, you shouldn’t include it in your page without escaping it first.
Example request:
$ curl "https://readthedocs.org/api/v3/search/?q=project:docs%20server%20side%20search"
import requests URL = 'https://readthedocs.org/api/v3/search/' params = { 'q': 'project:docs server side search', } response = requests.get(URL, params=params) print(response.json())
Example response:
{ "count": 41, "next": "https://readthedocs.org/api/v3/search/?page=2&q=project:docs%20server+side+search", "previous": null, "projects": [ { "slug": "docs", "versions": [ {"slug": "latest"} ] } ], "query": "server side search", "results": [ { "type": "page", "project": { "slug": "docs", "alias": null }, "version": { "slug": "latest" }, "title": "Server Side Search", "domain": "https://docs.readthedocs.io", "path": "/en/latest/server-side-search.html", "highlights": { "title": [ "<span>Server</span> <span>Side</span> <span>Search</span>" ] }, "blocks": [ { "type": "section", "id": "server-side-search", "title": "Server Side Search", "content": "Read the Docs provides full-text search across all of the pages of all projects, this is powered by Elasticsearch.", "highlights": { "title": [ "<span>Server</span> <span>Side</span> <span>Search</span>" ], "content": [ "You can <span>search</span> all projects at https://readthedocs.org/<span>search</span>/" ] } }, { "type": "domain", "role": "http:get", "name": "/_/api/v2/search/", "id": "get--_-api-v2-search-", "content": "Retrieve search results for docs", "highlights": { "name": [""], "content": ["Retrieve <span>search</span> results for docs"] } } ] }, ] }
Migrating from API v2
Instead of using query arguments to specify the project and version to search, you need to do it from the query itself, this is if you had the following parameters:
project: docs
version: latest
q: test
Now you need to use:
q: project:docs/latest test
The response of the API is very similar to V2, with the following changes:
project
is an object, not a string.version
is an object, not a string.project_alias
isn’t present, it is contained in theproject
object.
When searching on a parent project,
results from their subprojects won’t be included automatically,
to include results from subprojects use the subprojects
paramater.
API v2 (deprecated)
Note
Please use our API v3 instead, see Migrating from API v2.
- GET /api/v2/search/
Return a list of search results for a project, including results from its Subprojects. Results are divided into sections with highlights of the matching term.
- Query Parameters:
q – Search query
project – Project slug
version – Version slug
page – Jump to a specific page
page_size – Limits the results per page, default is 50
- Response JSON Object:
type (string) – The type of the result, currently page is the only type.
project (string) – The project slug
project_alias (string) – Alias of the project if it’s a subproject.
version (string) – The version slug
title (string) – The title of the page
domain (string) – Canonical domain of the resulting page
path (string) – Path to the resulting page
highlights (object) – An object containing a list of substrings with matching terms. Note that the text is HTML escaped with the matching terms inside a
<span>
tag.blocks (object) –
A list of block objects containing search results from the page. Currently, there is one type of block:
section: A page section with a linkable anchor (
id
attribute).
Warning
Except for highlights, any other content is not HTML escaped, you shouldn’t include it in your page without escaping it first.
Example request:
$ curl "https://readthedocs.org/api/v2/search/?project=docs&version=latest&q=server%20side%20search"
import requests URL = 'https://readthedocs.org/api/v2/search/' params = { 'q': 'server side search', 'project': 'docs', 'version': 'latest', } response = requests.get(URL, params=params) print(response.json())
Example response:
{ "count": 41, "next": "https://readthedocs.org/api/v2/search/?page=2&project=read-the-docs&q=server+side+search&version=latest", "previous": null, "results": [ { "type": "page", "project": "docs", "project_alias": null, "version": "latest", "title": "Server Side Search", "domain": "https://docs.readthedocs.io", "path": "/en/latest/server-side-search.html", "highlights": { "title": [ "<span>Server</span> <span>Side</span> <span>Search</span>" ] }, "blocks": [ { "type": "section", "id": "server-side-search", "title": "Server Side Search", "content": "Read the Docs provides full-text search across all of the pages of all projects, this is powered by Elasticsearch.", "highlights": { "title": [ "<span>Server</span> <span>Side</span> <span>Search</span>" ], "content": [ "You can <span>search</span> all projects at https://readthedocs.org/<span>search</span>/" ] } } ] }, ] }