Facts API

Random Facts API

A full fledged facts API, one of the best in the world. Get random facts based on a category, drawn from hundreds of thousands of fact entries in our database. To provide finer granularity subcategory is also supported. You can store private facts and retrive them back. On this day style historic facts are supported too.

To see some of the facts in our database you can look at our random facts generator here.

API End Points

	https://api.fungenerators.com
	

Ratelimiting

Some of our API calls are public. To maintain our service level we ratelimit the number of API calls. For public API calls this is 60 API calls a day with distribution of 5 calls an hour. For paid plans this limit is increased according to the service level described in the plan.

Authentication

For public calls you don't need to pass any API key. Just invoke the endpoint (see examples below). For paid subscriptions you need to pass the API key.

Currently we support API Key based authentication. Please set a request header 'X-FunGenerators-Api-Secret' with value of your API key. Alternatively you can also pass api_key= as a request parameter, though we strongly discourage this mode of passing the key.

API Documentation

Get a Random Fact

GET /fact/random

curl -X GET "http://api.fungenerators.com/fact/random?category=Countries&subcategory=USA" -H  "accept: application/json" -H  "X-Fungenerators-Api-Secret: api_key"

{
  "success": {
    "total": 1
  },
  "contents": {
    "fact": "The most iconic donut shop in Hollywood is Randy's Donuts. It has appeared in many movies including Crocodile Dundee and Iron Man 2.",
    "id": "VbUC4jKvaxzHNgs2FRUthweF",
    "category": "Food ",
    "subcategory": "Donuts "
  }
}

Search for a random Fact

GET /fact/search

curl -X GET "http://api.fungenerators.com/fact/search?query=Amazon" -H  "accept: application/json" -H  "X-Fungenerators-Api-Secret: api_key"

{
  "success":{"total":1},
  "contents":{
    "fact":"There are more than 1,100 known tributaries flowing into the Amazon River. Tributaries are sources of water such as a small river, stream  or other water flow that reaches the river.",
    "id":"LCN5KlSn6BMpcm3ruXhfGweF",
    "category": "Rivers",
    "subcategory": "Amazon River"
    
  }
  
}

Create a Fact Enry

PUT /fact

curl -X PUT "http://api.fungenerators.com/fact?fact=January%2020th%20is%20the%20day%20in%201941%20that%20a%20Nazi%20officer%20is%20murdered%20in%20Bucharest%2C%20Romania%2C%20sparking%20a%20rebellion%20and%20pogrom%20by%20the%20Iron%20Guard%2C%20killing%20125%20Jews%20and%2030%20soldiers.&category=Numbers&subcategory=Date&tags=numbers%2C%20historical" -H  "accept: application/json" -H  "X-Fungenerators-Api-Secret: api_key"

{
    "success": {
        "total": 1
    },
    "contents": {
        "id": "62D6iKM9GSlJxK5nrMf9XwrE"
    }
}

Get a Fact entry

GET /fact

curl -X GET "http://api.fungenerators.com/fact?id=LCN5KlSn6BMpcm3ruXhfGweF" -H  "accept: application/json" -H  "X-Fungenerators-Api-Secret: api_key"

{
  "success":{"total":1},
  "contents":{
    "fact":"There are more than 1,100 known tributaries flowing into the Amazon River. Tributaries are sources of water such as a small river, stream  or other water flow that reaches the river.",
    "id":"LCN5KlSn6BMpcm3ruXhfGweF",
    "category": "Rivers",
    "subcategory": "Amazon River"
    
  }
  
}

Delete a Fact

DELETE /fact

In curl this request will look something like this

curl -X DELETE "http://api.fungenerators.com/fact?id=uHBbOfP7ECfVkeQrE" -H  "accept: application/json" -H  "X-Fungenerators-Api-Secret: api_key"

{
    "success": {
        "total": 1
    },
    "contents": {
        "mesg": "Fact uHBbOfP7ECfVkeQrE is deleted"
    }
}

Get a random historic event

To get a random hsitoric event on a given day ( defaults to current day ) use the following endpoint.

GET /fact/onthisday/event

The above call should produce something like the following

              {
                "success": {
                  "total": 1
                },
                "contents": {
                  "id": "KVlPpVL119DtLFtphgOxqQeF",
                  "day": "26",
                  "month": "8",
                  "year": "1883",
                  "date": "1883-8-26",
                  "event_type": "event",
                  "event": "The Indonesian island of Krakatoa erupts in the largest explosion recorded in history, heard 2,200 miles away in Madagascar."
                }
              } 

API Console

The following are the API calls you can make. You can try out / test the calls right from this page. Please note, javascript needs to be enabled to see the documentation below.

Subscribe