[Click here to jump right to the Reddit APIs documentation]
First, a warning. Putting together your own dynamic embeds based on Reddit data, rather than using a service, is not a choice that lends itself to an easy or robust solution. Reddit often retires public endpoints, and there can be mixed documentation about those that do exist, which is part of why I am writing this post.
An alternative to rolling your own solution:
First, before getting into a custom solution, I’ll just point out that Embedly, which is a service that lets you dynamically embed external content on your site, is an official partner of Reddit. Why does this matter? Well, if Reddit makes a change to their API, you better believe they are going to work with Embedly to make sure their embeds keep working. Some random dev that doesn’t pay to use their API? Not so much.
If you hit the “share” button below a Reddit post, and select “embed” as the option, the embed code it generates for you to use is actually Embedly code! Or, you can generate the same code using Embedly’s generator.
Embedly also has hundreds of providers other than Reddit. If you are looking to add other external content to your site or app, think about whether it is worth the time to build out a custom connector for each source, rather than one single integration with Embedly.
I’m not an employee of Embedly or even a user of their service, but just want to make it clear what your options are if you don’t want to reinvent the wheel. Now, for those that do, or are looking for general information on Reddit APIs, read on.
Reddit API Endpoints, Notes, and Examples:
Main docs: https://www.reddit.com/dev/api/
Not advised:
- https://www.reddit.com/oembed?url={reddit_post_or_comment_link}
- Example request: Link
- The problem with this endpoint, is that it does not return a proper CORs header
- This means the request get blocked in all major browsers
- This might not be a problem for you if you are building a desktop application or other non-web app
- The information returned from this is also pretty basic
Good:
- The “.json” trick – e.g. {reddit_url}.json
- Example: Link
- This is actually an insanely cool trick. Currently, you can take pretty much any Reddit permalink URL (post, comment, even boards) and just add
.jsonto the end of the URL to get back JSON formatted data! - This approach even returns a wildcard
access-control-allow-originheader, so you can easily use it with AJAX and not have CORs issues! - Downside: The data that is returned from each URL is not really filtered…
- This is bad if you simply want to get the title of a post and its preview image, as you add unnecessary latency and bandwidth use
- However, this is good if you are looking to get tons of data at once (for example, to generate a preview of a popular thread).
- You can limit the number of returned children elements by using the
limit={#}querystring parameter - A benefit to this method is that you don’t need to know the type (type prefix) of the object beforehand
- Official
/infoAPI endpoint
Parsing API JSON data
Both the .json trick and /info API endpoints return JSON data.
- For
.json, it is returned as an array with two elements (objects).- The first element is the “thing” itself (post, comment, etc.)
- The second element is the children of the thing
- For
/info, it is returned a single object, of the thing itself - Each element contains two sub-objects:
dataandkind(type of thing)datacontains achildrenarray, which can contain many sub-elements
To get the title of a post / article with the .json trick, you would use `jsonData[0].data.children[0].data.title`, since the post itself is the first child of the first element (itself).
Image 403 Forbidden Error from API:
If you grabbed an image URL off the API response and tried to use it, you might have ran into a “Error 403 Forbidden” message and/or HTTP error status. The most likely culprit is that the URL got messed up due to encoding / escaping.
Whether you did or did not use raw_json=1 option with your API request, you simply need to decode some encoded HTML entities within the image URL. With JavaScript, you can use this code to decode it.
If you are not using JS, search for “decoding HTML entities” + your programming language to see if there is a library or pattern you can use. Or simply do a string search and replace of “&” with “&”, since that is the usual culprit.
For embeds only:
- If all you need to do is embed a single comment or comment chain in a website, there is a quick trick you can use, no API required:
- I can’t find a corresponding trick to generate an embed URL for regular posts instead of comments 🙁
Reddit IDs / ID36 / T_
One of the things you might see glossed over through API documentation and various help threads is references to a ID36 string, or t_ Reddit ID. What is this? Well, if you look closely at pretty much any Reddit URL, you will start to see a pattern:
reddit.com/r/food/comments/60jxzo/homemade_breakfast_sugar_cookies/df71am8/
See the highlighted parts? Those are Reddit IDs, specifically ID36, or base36 strings. Why the “36”? Well, the IDs will always contain only lowercase letters (26 characters in the alphabet) and/or digits (0-9, which is 10 choices) –> 26 letters + 10 digits = 36 choices!
Type prefix (t_) and fullnames
A “fullname” in terms of the Reddit API is the type prefix (t1_, t2_, etc.), plus the ID36. So, an example would be “t1_df71am8”, which corresponds to a comment (type t1) with an ID of “df71am8”. You can find the table of type prefixes here and more info about fullnames, here.
Building a Custom Embed – Demo:
To put together some of the API basics I’ve covered in this post, and demonstrate how you might use them, I’ve thrown together a quick demo. This is just a little bit of JS + HTML + CSS, that dynamically generates a Reddit post summary card, based on an input URL. It uses the /info API endpoint, and JavaScript’s fetch() web API. You can press the “demo” button to test it with the example Reddit thread used throughout this post.