General operation

The jokes are available at http://api.icndb.com. Use HTTP GET to retrieve what you want (read on below for more details). Results can returned as raw JSON data (the default case) or using a JavaScript callback function for script communication.

JSON

In the default case, the result will always look like this:

{ "type":
, "value":
 }

The type will be “success” on success and something else when something went wrong (more details below). An example of the result of a successful request:

{ "type": "success", "value": { "id": 268, "joke": "Time waits for no man. Unless that man is Chuck Norris." } }

Using callback functions

Next to returning raw JSON data, it is also possible to automatically feed the results into a callback function. This is useful for script communication in case regular XMLHttpRequest does not work.

To use a callback function, use the following GET parameter:

?callback=

The callback function will retrieve the parsed JSON as stated above.

Changing the name of the main character

The API permits changing the name of the main character when fetching a joke. To do this, use the following GET parameters:

?firstName=
?lastName=

Example: To retrieve one random joke with main character called “John Doe”, fetch the URL:

http://api.icndb.com/jokes/random?firstName=John&lastName=Doe

The result will be similar to before, for example:

{ "type": "success", "value": { "id": 268, "joke": "Time waits for no man. Unless that man is John Doe." } }

Escaping special characters

Some jokes contain some special characters such as “, & or <. These special characters can make it hard to show the joke correctly or can even skrew up the syntax of the result. To fix this, the API escapes special characters before returning the result. There are two options: HTML encoding or JavaScript encoding.

HTML encoding is the default. In this case, &, ” (double quotes), < and > are encoded in their respective HTML format (e.g., &amp;). In this case, you can directly insert the resulting joke in an HTML page without errors.

With JavaScript encoding, only quotes (both double and single) are escaped. In this case, backslashes are added (e.g., “Chuck’s fist” becomes “Chuck\’s fist”). JavaScript encoding is only used when you request a joke with the following GET parameter:

?escape=javascript

Fetching a random joke

URL:

http://api.icndb.com/jokes/random

Result:

{ "type": "success", "value": { "id": , "joke":
 } }

Fetching multiple random jokes

URL:

http://api.icndb.com/jokes/random/

Example:

http://api.icndb.com/jokes/random/3

Result:

{ "type": "success", "value": &gt; }

Example:

{ "type": "success", "value": [ { "id": 1, "joke": "Joke 1" }, { "id": 5, "joke": "Joke 5" }, { "id": 9, "joke": "Joke 9" } ] }

Limiting categories

The jokes in the database are given categories such as “nerdy” or “explicit”. When fetching multiple jokes, it is possible to limit the scope to some of these categories or exclude some of them, as shown below. The list of categories can be retrieved as shown in one of the next sections.

To limit the jokes to certain categories, use the following GET parameter:

http://api.icndb.com/jokes/random?limitTo=Array

Example:

http://api.icndb.com/jokes/random?limitTo=[nerdy]
http://api.icndb.com/jokes/random?limitTo=[nerdy,explicit]

Similarly, to exclude jokes from certain categories, use the following GET parameter:

http://api.icndb.com/jokes/random?exclude=Array

Example:

http://api.icndb.com/jokes/random?exclude=[nerdy]
http://api.icndb.com/jokes/random?exclude=[nerdy,explicit]

Fetching a specific joke

URL:

http://api.icndb.com/jokes/

Example:

http://api.icndb.com/jokes/15

Result and example: same as with random joke.

Fetching the number of jokes

URL:

http://api.icndb.com/jokes/count

Result:

{ "type": "success", "value":  }

Example:

{ "type": "success", "value": 549 }

Fetching the list of joke categories

URL:

http://api.icndb.com/categories

Result:

{ "type": "success", "value": &gt; }

Example:

{ "type": "success", "value": [ "nerdy", "explicit", "chuck norris", "bruce schneier" ] }
 

83 Responses to API

  1. how is development going? :)

    • admin says:

      I have to be honest, not much going on for the moment… Having been busy a lot, but I will continue the project when I can. For the record: planned on adding more categories, increasing the number of jokes and developing the latest-jokes-function.

  2. andy says:

    you get a specific joke part of the api is btw already working:

    http://api.icndb.com/jokes/1
    http://api.icndb.com/jokes/$jokenumber

  3. When you call the count it says 550 right now but there are jokes with an id over 550. That’s because there are some ids that aren’t assigned to a joke, and if you call them you get a fatal error. Could you fix this please?

    • admin says:

      Hi Richard,

      Why is this a problem? I’ve though about this, but this would require shifting existing jokes to lower ids when a joke is removed. I chose to keep each joke at its original id.

  4. could you give a method to get the highest id?

  5. don’t mind the request, I will redo some stuff in the application and I won’t need it now. Thank you for replying though.

  6. tim says:

    Hi, brilliant site. I used your DB in a learning experience and built an Android app for this…see Chuck Norris Jokes. Some of these jokes are cut off in the database. Is there any way to complete them? E.g. “Chuck Norris is expected to win gold in every swimming competition at the 2008 Beijing Olympics, even though Chuck Norris does not swim. This is because when Chuck Norris enters the water, the water gets out of his way and Chuck Norris simply walks across the”.

    • admin says:

      Hey,

      Thanks for the reply, I appreciate you appreciating it :) About the joke: thanks for the bug report, I’ve removed four incomplete jokes.

      If you have other remarks or questions, be sure to let me know!

  7. This has got to be one of the neatest APIs. :)

  8. [...] Google search turned up The Internet Chuck Norris Database, a hilarious site which even contains a REST API!   Great, so this means we can get a single joke back each time by writing appropriate [...]

  9. Yuval says:

    Hi,
    As you’ve already noticed I’ve written a TFS 2010 build activity that will show a random Chuck Norris joke when a build is run. I hope this will make people run their builds more!
    The blog post is here. Thanks for the great work!

  10. Moeses says:

    i’m using python, i’m a new user with it, and i was wondering how can i just get the joke to display instead of the whole thing??

    • admin says:

      Hi Moeses,

      I guess with “the whole thing” you mean the whole json object? To print a random joke in python, I would do something like this:

      import urllib2
      import json

      req = urllib2.Request("http://api.icndb.com/jokes/random")
      full_json = urllib2.urlopen(req).read()
      full = json.loads(full_json)
      print full['value']['joke']

      Hope this helps!

      • Moeses says:

        that does help a lot. had to change some things around to use for my personal siriServer for my iPhone 4. so now whenever i say chuck norris to siri i get a random quote. Thanks so much again. really cool API.

  11. SNXRaven says:

    How would I store multiple jokes in that python script

    • admin says:

      It’s not really clear to me what you mean by “storing multiple jokes”, but to fetch multiple, you can just provided the needed number to the API:

      http://api.icndb.com/jokes/random/5

      In that case, the value in the result will be an array of jokes (see API documentation), so we can print all of them like this:

      import urllib2
      import json

      req = urllib2.Request("http://api.icndb.com/jokes/random/5")
      full_json = urllib2.urlopen(req).read()
      full = json.loads(full_json)
      for joke in full['value']:
          print joke['joke']

  12. Dan Jones says:

    I found a problem with your API. When a string contains double quotes, the quotes aren’t properly escaped, thereby breaking the JSON data.

    Here’s an example I got:
    { “type”: “success”, “value”: { “id”: 394, “joke”: “”Let the Bodies Hit the Floor” was originally written as Chuck Norris’ theme song.”, “categories”: ["chuck norris"] } }

    This should be instead:
    { “type”: “success”, “value”: { “id”: 394, “joke”: “\”Let the Bodies Hit the Floor\” was originally written as Chuck Norris’ theme song.”, “categories”: ["chuck norris"] } }

  13. Dan Jones says:

    It would be good if your API returned the proper mime-type. The servers returns it as text/html, rather than application/json.

  14. 0x89 says:

    Is it really necessary to HTML-Encode the quotes? Its nasty to decode safely in Javascript without being vulnerable to XSS-Attacks.

    Couldn’t you just quote them instead? (ideally you would version the REST API so that clients that depend on the old behavior could still use the old one..).

    There are also some question marks where there should be single quotes, e.g. http://api.icndb.com/jokes/141.

    Apart from that: good work, keep it up!

    • admin says:

      Hi ox89,

      I added the option ?escape=javascript (also updated the docs above), this will add backslashes to quotes instead of escaping HTML special characters.

      The issue with joke 141 was not the result of incorrect escaping, it was in the database like that. Fixed it, I’ll go through the other jokes as well.

      • 0x89 says:

        Thanks, that was very responsive. In the meantime, I used http://www.strictly-software.com/htmlencode to decode the html entities.

        Btw. this is what I have built:
        https://github.com/marvinthepa/chuckfluence

        • admin says:

          No problem, and cool project!

          Your XSS remark before interests me. I don’t see how client-side decoding of the HTML encoding makes you vulnerable to XSS, could you elaborate a bit?

          • 0x89 says:

            Well, lets say someone takes over your database, and changes one of the quotes to

            alert(‘you haven been pwned’)

            If my plugin would insert this within the page
            using

            $(‘#id’).html(…)

            What would happen? The attacker could execute arbitrary javascript code in the context of my page. This is what I understand as XSS. I might be mistaken though as I don’t know a lot about these topics.

            Btw. the attacker wouldn’t even have to take over your database, as you don’t use https we would also be vulnerable to man-in-the-middle-attacks.

          • 0x89 says:

            whoops, your blog engine stripped the tags out of my post..

            the alert needs to be surrounded by script tags:

            alert('you have been pwned')

            hope this works this time..

          • admin says:

            It still didn’t work, but I get the picture :) You are correct to be worried about this kind of thing, correct escaping of JSON and HTML indeed is a difficult problem.

            What you are describing is an injection attack. Originally, the only way to decode JSON was to use eval(json), in which case JavaScript code in the variable json would also be run, leading to JavaScript injection. Now, browsers allow native JSON decoding with JSON.parse(), making it impossible to sneak in code there.

            For HTML this is more difficult, browsers do not offer a method for isolating parts of the HTML tree or something similar. So $(‘#id’).html(...) could still contain HTML such as a script tag. That’s actually why I escape everything on the server, a joke’s joke attribute should never contain HTML tags, making it easier for the client.

            However, this is still a matter of trust in the web service, its correct functioning, its admin not being malevolent, the security of the web service, the security of the transport etc. Complex problem :)

  15. Sorin says:

    Hi,

    Just wanted t say “Cool idea!” and to point out a small issue, as visible at http://api.icndb.com/jokes/394?escape=javascript&firstName=John&lastName=Doe

    Notice the John Doe’ in the response.

    By the way, is this name replacing feature related to Chuck Norris sueing Penguin (methinks) for using his name?

    • admin says:

      Hi Sorin,

      Thanks for the bug report. The error is a genitive, “Chuck Norris’ theme song”, which should be “John Doe’s theme song” for names not ending with an s.

      And no, this is not a feature against legal issues, it’s just a cool feature. ICNDb is just a database of public jokes, this adds some flavor to it :)

      • Daniel Heath says:

        This is part of a larger difficulty of e.g. conjugating correctly when you change the name.

        For instance “Real Men”, “Ada Lovelace”, “Chuck Norris” all conjugate differently for common words (they/she/he) and tenses (wants an egg / want an egg).

  16. Ram Kashyap says:

    Hi Admin,

    Undoubtedly a very useful API for app developers ;-) Is there a way that I can remove the adult jokes? you know most of the stores are made for 13+ old years, but there is a lot of 18+ material, is there a neat jokes category?

  17. Hi … I created an API wrapper in C#, so you can easily access this API from C# apps :)

    https://github.com/joelmartinez/icndb-csharp

  18. Cool project!

    Used this to email all of our product development team before coming to work in the morning to have some laughs :D

    Made a PHP client for the API to contribute back.

    https://github.com/tistaharahap/chuck-norris-php

  19. David says:

    Hey, how many jokes have you got so far? It’d be cool to display some stats :D Awesome jokes BTW.

  20. Ian Neubert says:

    Howdy Admin,

    It looks like your JSON is sometimes invalid:
    http://api.icndb.com/jokes/34
    http://api.icndb.com/jokes/278

    It’s not escaping things properly.

    Thanks for the site and the API!

  21. Pyry Pakkanen says:

    Is the escaping working correctly? I’m not seeing any difference between:
    http://api.icndb.com/jokes/141?escape=javascript
    http://api.icndb.com/jokes/141?escape=html

  22. Cloudwalker says:

    Is it just me or callback stopped working?

  23. aurel says:

    hi, first of all, thanks for your work!

    I’am thinking about integrating random jokes in my web site, as a loader message.

    so i’am thinking : if you had a database of jokes in other languages (french for example :)), would it be possible for you to add a language input in the api ?

  24. Mary says:

    I just noticed if you enter a name that does not end with the s there is a problem.
    Original: Chuck Norris’ whatever
    Problem with: Tom William’ whatever –> missing the s

  25. Nice API and good jokes. I was looking for random posts for my twitter app I designed recently. It pulls random jokes from this API and allows user to post to their twitter account.

    Here is the app: http://twitter.jayeshcp.com

    I hope you will like it :)

    Thanks for sharing this API.

    • admin says:

      Very cool! I had this idea myself, but didn’t come around to it. A nice addition would be to change the name of Chuck Norris into the name of the Twitter user, which you can do with the API.

  26. Erik says:

    You sir are awesome.

    If you had a raw “curl”-able url as well, that’d be great for message of the day services.

    I actually use your api for my mutt email signature!

    Thanks.

  27. Don says:

    This is pretty awesome :) For business/HR reasons it would be handy to be able to exclude categories (like “explicit”). I currently just loop and reissue if I get one of those.

  28. Zaw says:

    Hi

    just wondering if this api is still in service? i wanna use it in making android app for uni assignment. and also what are the type of categories that you have for the jokes?thanks!

  29. Ali Nazari says:

    hi my friend :)
    may i use this api in a commercial android app freely? :D
    tnx

  30. I just finished up a Google Glass app. I’ll release it as soon as Google provides a way to distribute Glass apps, and give you a huge shout-out in the description.

    Thanks for providing a great API for a great database!

    Chuck Me for Google Glass

  31. Daksh says:

    I am an Android developer and made an application using ‘random’ joke api in Android. Thank you for providing such great database and api.

    Here is my link to the application on Google Play Chuck Norris Jokes on Google Play

    I also mention your website in app description in Google Play and in credits in application for providing such large database of jokes.

  32. Alex Key says:

    Hi,

    This is a great service, I’m making use of it in a mobile application.

    However unfortunately the escaped single quotes in the javascript encoded JSON is causing trouble.

    Although it seems sensible to javascript encode then i.e. ‘ becomes \’

    The JSON standard only specifies a small number of things that can be escaped. You don’t need to encode single quotes.

    In desktop browsers they are looser with this standard and it doesn’t cause a problem, however in a mobile environment (not the web browser itself, but e.g. iOS itself)
    json.Parse() is stricter and will throw an exception when reaching a \’

    Here on the standard page http://www.json.org/ you can see that single quotes are not on the list.

    It would be great if you can not encode the single quotes please.

    Keep up the good work.

    -thanks
    Alex.

  33. Jason says:

    Hi, awesome API :-)

    I was hoping you could help clarify the way the ?exclude filter works. I see an example in the docs that calls for (what looks like) a JSON encoded array? However, in the comments I see just a string example ?exclude=explicit

    Neither of these seem to work all the time for me. I am currently using ?exclude=explicit and I just got one about an erection.

    • admin says:

      Hi,

      It’s both actually, but the recommended usage is using an array (without quotes), e.g.:

      http://api.icndb.com/jokes?exclude=[explicit,nerdy]

      or

      http://api.icndb.com/jokes?exclude=[explicit]

      The reason you still got a joke about an erection is that is was not yet labeled explicit. That has been fixed :) See http://api.icndb.com/jokes/229

      Is it clear now?

  34. Ash Menon says:

    Just wanna point out that in some of the quotes, the lastName parameter isn’t always properly rendered.

    http://api.icndb.com/jokes/random?firstName=Jeremy&lastName=Peet

    In some cases I got Jeremy Norris, instead of Jeremy Peet.

    (am trying to replicate this but I can’t seem to. Maybe it was just a faulty query on my part :D)

    • admin says:

      Hi,

      I checked out the database and there does not seem to be anything wrong with the jokes. I also can’t replicate the problem. If you manage to replicate it again, let me know and I will check it out.

  35. gaarf says:

    Thanks for the API!

    I used it while playing with Angular.js – resulting in this app: http://jsbin.com/kinara

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Set your Twitter account name in your settings to use the TwitterBar Section.