Quotable

Quotable is a free, open source quotations API. It was originally built as part of a FreeCodeCamp project. The database includes over 2000 quotes by 900 authors.

• Servers
• API Reference
  • Get random quote
  • List Quotes
  • Get Quote By ID
  • List Authors
  • Get Author By ID
  • List Tags
• Usage
  • Live Examples
• Contributing

Servers

Name	URL	Description
Staging	staging.quotable.io	Synced with the master branch of this repository
Production	api.quotable.io	The primary API server

API Reference

Get random quote

Returns a single random quote from the database

GET /random

Query parameters

param	type	Description
maxLength	Int	The maximum Length in characters ( can be combined with minLength )
minLength	Int	The minimum Length in characters ( can be combined with maxLength )
tags	String	Filter random quote by tag(s). Takes a list of one or more tag names, separated by a comma (meaning AND) or a pipe (meaning OR). A comma separated list will match quotes that have all of the given tags. While a pipe (|) separated list will match quotes that have either of the provided tags.
authorId	String	Filter random quote by authorId(s). Takes a list of one or more authorId, separated by a pipe (meaning OR). A pipe (|) separated list will match quotes that have either of the provided authorId.
author	String	Filter random quote by author(s). Takes a list of one or more author names, separated by a pipe (meaning OR). A pipe (|) separated list will match quotes that have either of the provided author name.

Response

{
  _id: string
  // The quotation text
  content: string
  // The full name of the author
  author: string
  // The length of quote (number of characters)
  length: number
  // An array of tag names for this quote
  tags: string[]
}

Examples

Random Quote try in browser

GET /random

Random Quote with tags "technology" AND "famous-quotes" try in browser

GET /random?tags=technology,famous-quotes

Random Quote with tags "History" OR "Civil Rights" try in browser

GET /random?tags=history|civil-rights

Random Quote with a maximum length of 50 characters try in browser

GET /random?maxLength=50

Random Quote with a length between 100 and 140 characters try in browser

GET /random?minLength=100&maxLength=140

List Quotes

Get a paginated list of all quotes. This method supports several filter and sorting options.

GET /quotes

Query parameters

param	type	Description
authorId	String	Filter quotes by author ID.
limit	Int	Min: 1 Max: 100 Default: 20 The number of quotes to return per request. (for pagination).
skip	Int	Min: 0 Default: 0 The number of items to skip (for pagination).
maxLength	Int	The maximum Length in characters ( can be combined with minLength )
minLength	Int	The minimum Length in characters ( can be combined with maxLength )
tags	String	Filter quotes by tag(s). Takes a list of one or more tag names, separated by a comma (meaning AND) or a pipe (meaning OR). A comma separated list will match quotes that have all of the given tags. While a pipe (|) separated list will match quotes that have either of the provided tags.

Response

{
  // The number of quotes returned by this request
  count: number
  // The total number of quotes matching this request
  totalCount: number
  // The index of the last quote returned. When paginating through results,
  // this value would be used as the `skip` parameter when requesting the next
  // "page" of results.
  lastItemIndex: number
  // The array of quotes
  results: Array<{
    _id: string
    // The quotation text
    content: string
    // The full name of the author
    author: string
    // The length of quote (number of characters)
    length: number
    // An array of tag names for this quote
    tags: string[]
  }>
}

Get Quote By ID

Get a quote by its ID

GET /quotes/:id

Response

{
  _id: string
  // The quotation text
  content: string
  // The full name of the author
  author: string
  // The length of quote (number of characters)
  length: number
  // An array of tag names for this quote
  tags: string[]
}

List Authors

Get a paginated list of all authors. By default, authors will be returned in alphabetical order (ascending).

GET /authors

Query parameters

param	type	Description
sortBy	enum: ['name', 'quoteCount']	Default: "name" The field used to sort authors.
sortOrder	enum: ['asc', 'desc']	Default: "asc" The order results are sorted in.
limit	Int	Min: 1 Max: 100 Default: 20 The number of authors to return per request. (for pagination)
skip	Int	Min: 0 Default: 0 The number of items to skip (for pagination)

Response

{
  // The number of authors return by this request.
  count: number
  // The total number of authors matching this request.
  totalCount: number
  // The index of the last item returned. When paginating through results,
  // this value would be used as the `skip` parameter when requesting the next
  // "page" of results. It will be set to `null` if there are no additional results.
  lastItemIndex: number | null
  // The array of authors
  results: Array<{
    // A unique id for this author
    _id: string
    // The authors full name
    name: string
    // The number of quotes by this author
    quoteCount: string
  }>
}

Get Author By ID

Get a specific author by ID. The response includes all quotes by the given author.

GET /authors/:id

Response

{
  // A unique id for this author
  _id: string
  // The authors full name
  name: string
  // The number of quotes by this author
  quoteCount: string
  // The array of quotes by this author (not paginated)
  quotes: Array<{
    _id: string
    // The quotation text
    content: string
    // The full name of the author
    author: string
    // An array of tag names for this quote
    tags: string[]
    // The length of quote (number of characters)
    length: number
  }>
}

List Tags

GET /tags

Get a list of all tags

Query parameters

param	type	Description
sortBy	enum: ['name', 'quoteCount']	Default: "name" The field used to sort tags.
sortOrder	enum: ['asc', 'desc']	Default: depends on sortBy The order in which results are sorted.

Response

{
  // The number of all tags by this request
  count: number
  // The array of tags
  results: Array<{
    _id: string
    name: string
  }>
}

Usage

Get a random quote (fetch)

fetch('https://api.quotable.io/random')
  .then(response => response.json())
  .then(data => {
    console.log(`${data.content} —${data.author}`)
  })

Get a random quote (async/await)

async function randomQuote() {
  const response = await fetch('https://api.quotable.io/random')
  const data = await response.json()
  console.log(`${data.content} —${data.author}`)
}
randomQuote()

Get a random quote (JQuery)

$.getJSON('https://api.quotable.io/random', function (data) {
  console.log(`${data.content} —${data.author}`)
})

Live Examples

Basic Random Quote (CodePen)

React Random Quote (CodeSandbox)

Contributing

All contributions are welcome! For more info on how to contribute, check out the Contributors Guide