herliansyah / quotable

Random Quotes API

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 Methods
  • 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 Methods

Get random quote

Returns a single random quote from the database

Path

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.

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 Quotes

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

Path

GET /quotes

Query parameters

param	type	Description
author	String	Filter quotes by author name. Supports fuzzy search.
authorId	String	Filter quotes by author ID.
limit	Int	The number of quotes to return per request. (for pagination).
skip	Int	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

Path

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).

Path

GET /authors

Query parameters

param	type	Description
name	String	Search for authors by name. Supports fuzzy search.
sortBy	enum: ['name', 'quoteCount']	The field used to sort authors. Default is 'name'
sortOrder	enum: ['asc', 'desc']	The order results are sorted in. Default is 'asc'
limit	Int	The number of authors to return per request. (for pagination)
skip	Int	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.

Path

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 a list of all tags

Path

GET /tags

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