ZenQuotes Documentation

The ZenQuotes API is an incredibly easy to use data feed for your website or app. Developers love integrating our service into their projects. Some common use cases include: start pages, Discord bots, mental health apps, and IoT devices.

It is our goal to provide a quality, reliable API that both inspires and provokes thought. Our collection of quotes are specially curated by the development team and are never auto-scraped from the internet like you will find with most other low quality API providers.

In this guide we will go over each available call option and best practices for development. Please note that you may need an API key and active subscription to get a response from some options, see the Use Limits section for more information.

Contents

  1. Basic API Structure
  2. Response
  3. How to Fetch Quotes for your Website or App
  4. Request Quotes from a Specific Author
  5. Get a quote for daily inspiration
  6. Pull a single inspirational quote
  7. Run your own version of ZenQuotes
  8. API Usage Limits and Attribution

1. Basic API Structure

ZenQuotes.io API calls are designed to be easy to use and understand. The result data is formatted as a JSON array. Pre-formatted HTML output is available in addition to raw individual values.

The basic elements of an API call are as follows:

https://zenquotes.io/api/[mode]/[key]?option1=value&option2=value

where:

https://zenquotes.io/api = ZenQuotes API URL. Required.
[mode] = Retrieval type [quotes, today, author, random]. Required.
[key] = API key for use with premium subscriptions, be sure to obfuscate or hide this in your source code to prevent hijacking. Optional.
[options] = Additional options. Optional.

Alternative GET request formats are also available for advanced users:
Example: https://zenquotes.io?api=[mode]&key=[your_key]&option1=value&option2=value

2. Response

The resulting API data is formatted as a JSON array. Pre-formatted HTML output is available in addition to raw individual values.

  • q = quote text
  • a = author name
  • h = pre-formatted HTML
[
  {
    "q": "Be where your enemy is not.",
    "a": "Sun Tzu",
    "h": "<blockquote>&ldquo;Be where your enemy is not.&rdquo; &mdash; <footer>Sun Tzu</footer></blockquote>"
  },
  {
    "q": "Keep your friends close, and your enemies closer.",
    "a": "Sun Tzu",
    "h": "<blockquote>&ldquo;Keep your friends close, and your enemies closer.&rdquo; &mdash; <footer>Sun Tzu</footer></blockquote>"
  },
  {
    "q": "Know yourself and you will win all battles.",
    "a": "Sun Tzu",
    "h": "<blockquote>&ldquo;Know yourself and you will win all battles.&rdquo; &mdash; <footer>Sun Tzu</footer></blockquote>"
  }
]

3. How to Fetch Quotes for your Website or App

https://zenquotes.io/api/quotes/[your_key]

This is the most efficient way for developers to load random quotes. Use the standard [quotes] API call and store the results as a variable in your project. This will keep a cache of quotes that you can loop locally rather than calling the server each time you want to display a new quote.

After a set interval (an hour or so), call the ZenQuotes API again to refresh your local app cache. Using this method will keep load times down and free up resources for others as your user base increases. In the event the API service is unavailable, you will still have an available data set in your app to pull from.

4. Request Quotes from a Specific Author

https://zenquotes.io/api/quotes/author/[author-name]/[your_key]

The [author] call is used to generate a batch of quotes by a single author in the database. You can reference the list of available authors through your account, convenient links are provided for you to copy. We are adding more figures every month and are open to suggestions from our users. Please send your candidates to support@zenquotes.io for consideration.

5. Get a quote for daily inspiration

https://zenquotes.io/api/today/[your_key]

Each day we feature a single quote from our database, which you can call using the [today] call. To reduce server load, this response should be loaded into your app cache and refreshed daily rather than making a call each time you want to display the quote in your project. New quote is generated at midnight server time (00:00 CST).

6. Pull a single inspirational quote

https://zenquotes.io/api/random/[your_key]

This is the most simple ZenQuotes API request and will generate a single, random quote on each call. Use the [random] call sparingly, as it has little practical use for large scale projects. You generally should be caching a batch of quotes in your app locally as described in the previous sections.

You may find the [random] call useful for generating a random quote of the day for your project rather than using the standard [today] call to set yourself apart from others. This call is also good for students first learning how to use the API.

If you wanted to pull a random quote from a specific author, it would be best to use the [quotes]/[author] call to load a local app cache and pull a random entry from there. However, it is possible to call [random]/[author].

7. Run your own version of ZenQuotes

https://zenquotes.io/api/[quotes or random]/[your_key]?custom=true

Premium subscribers have the ability to load up to 500 of their own custom quote entries and call them using their API key. You may import a .csv file or enter each quote manually from the account dashboard.

CSV files should be formatted as: quote, author – if using a spreadsheet program, Column A would be the quote text and Column B would be the author. Save as .csv and import to ZenQuotes.

To call your custom quotes, use a standard API call and append the option ?=custom=true to the end of the request. The API will now only filter for your custom quotes.

Figure 1: ZenQuotes Custom .csv file

8. API Usage Limits and Attribution

Requests are restricted by IP to 5 per 30 second period by default. An API key or registered IP is required for unlimited access and to enable Access-Control-Allow-Origin headers. We require that you show attribution with a link back to https://zenquotes.io/ when using the free version of this API.

Inspirational quotes provided by <a href="https://zenquotes.io/" target="_blank">ZenQuotes API</a>

Back to Guide Contents