repository·master·Indexed 24 days ago
https://github.com/lukepeavey/quotableA free, open-source RESTful API for accessing a database of quotes, authors, and tags. Version 0.3.0 provides endpoints to retrieve random quotes, list paginated quotes, search for authors via autocomplete, and perform advanced full-text searches using Atlas Search. Features include filtering by tags, author slugs, and character length, with a rate limit of 180 requests per minute per IP address.
Quotable is a free, open-source quotations API. It allows developers to retrieve random quotes, list quotes, search for authors, and more.
Base URL: https://api.quotable.io
Rate Limiting: The API enforces a rate limit of 180 requests per minute per IP address. Exceeding this limit will result in a 429 error.
When using the query parameter, you can perform complex searches using logical operators and field-specific prefixes.
Supported Fields:
content (default search path)authortagsSyntax Examples:
term1 AND term2, term1 OR term2, NOT term1author:john, tags:wisdomauthor:adams AND (freedom OR justice)"exact phrase here"The Quotable server is initialized by executing the entrypoint script. It requires a MongoDB connection and uses the PORT environment variable to determine which port to listen on. If PORT is not provided, it defaults to 4000.
To run the server, ensure your environment variables (including database connection strings) are configured via a .env file or your shell environment, then execute the script.
The /quotes/random endpoint returns an array of random quotes matching your specified criteria. Unlike paginated endpoints, this returns a simple JSON array of quote objects without pagination metadata.
| Parameter | Type | Description |
|---|---|---|
limit | integer | The maximum number of random quotes to return (defaults to 1). |
query | string | A search query for full-text search. Supports advanced syntax (see Advanced Querying). |
tags | string | A list of tags separated by a comma (,) or pipe (|). |
author | string | One or more author slugs, separated by a pipe (|). |
minLength | integer | Minimum quote length in characters. |
maxLength | integer | Maximum quote length in characters. |
If enableAdvancedQuery is active (default), the query parameter supports MongoDB Atlas Search queryString syntax:
<field>:<search term>. Supported fields are content, author, and tags.AND, OR, and NOT to combine terms.() to group expressions."phrase") or single quotes ('phrase') to search for an exact match.Example: query=author:adams AND (freedom OR justice) matches quotes where the author includes "adams" AND the content contains either "freedom" or "justice".
Limits:
To filter random quotes by a specific author, use the author parameter.
|).400 Bad Request error.Example: author=albert-einstein|mark-twain
Common usage patterns for the search endpoint:
GET /search/quotes?query=life+happinessGET /search/quotes?query=Kennedy&fields=authorGET /search/quotes?query="divided house"Use these examples to construct your requests to the /quotes/random endpoint:
Get 3 random quotes:
GET /quotes/random?limit=3Random quote with tags "technology" AND "famous-quotes":
GET /quotes/random?tags=technology,famous-quotesRandom quote with tags "History" OR "Civil Rights":
GET /quotes/random?tags=history|civil-rightsRandom quote with a maximum length of 50 characters:
GET /quotes/random?maxLength=50Random quote with a length between 100 and 140 characters:
GET /quotes/random?minLength=100&maxLength=140Common usage patterns for the /search/authors endpoint:
Search for specific name:
GET /search/authors?query=EinsteinAutocomplete search:
GET /search/authors?query=EinstMulti-term search (e.g., John Adams):
GET /search/authors?query=john+adamsThe GET /random endpoint returns a single random quote object.
Note: This method is deprecated. It is recommended to use the Get Random Quotes endpoint instead, which returns an array of quotes.
GET /randomRetrieve a paginated list of quotes. You can filter results by length, tags, and author, and control sorting and pagination.
| Param | Type | Description |
|---|---|---|
maxLength | Int | Maximum character length |
minLength | Int | Minimum character length |
tags | String | Filter by tags. Use a comma (,) for AND logic (must have all tags) or a pipe (|) for OR logic (must have at least one). Tag names are case-insensitive. |
author | String | Filter by author name or slug. Use a pipe (|) for multiple authors. |
authorId | String | deprecated - Use author instead. |
sortBy | enum | Sort field. Default: dateAdded. Values: dateAdded, dateModified, author, content. |
order | enum | Sort order. Values: asc, desc. Default depends on sortBy (strings default to asc, numbers/dates to desc). |
limit | Int | Results per page (Min: 1, Max: 150, Default: 20). |
page | Int | Page number (Min: 1, Default: 1). |
{
count: number,
totalCount: number,
page: number,
totalPages: number,
lastItemIndex: number,
results: Array<{
_id: string,
content: string,
author: string,
authorSlug: string,
length: number,
tags: string[]
}>
}GET /quotes?tags=love|happinessUse the GET /search/quotes endpoint to search for quotes by keywords, content, or author name. This endpoint is powered by Atlas Search and is optimized for search bar UIs.
Key features:
"phrase") to search for an exact match.fuzzyMaxEdits and fuzzyMaxExpansions.Retrieve a single quote object using its unique _id.
Endpoint: GET /quotes/:id
Response Format:
{
_id: string,
content: string,
author: string,
length: number,
tags: string[]
}GET /quotes/:id