How to get started with the REST API?




I know this might be a bit of an obvious and easy question but I’m completely lost on how to pull Tweets onto a site using the REST API. I kind of understand what I need to include from the JSON file, but I’m just lost on how to actually request this and display it on a page.

I’m assuming this is the kind of thing I need to include (see the JSON example); but I don’t really know where to go from here. I’ve not used REST APIs before so sorry for my lack of knowledge on them.



Thanks for the question!

If you’re simply looking to embed Tweets into a website, your easiest route is likely to be one of our widgets. These allow individual Tweets, Timelines, Collections or Moments to be embedded into a site easily. There’s also a Wordpress plugin that we provide.

If you want to pull Tweets in yourself, then you’ll need to do some work with the API, and write some code. Choose the appropriate endpoint, preferably using a well-known and up-to-date API client library, and then parse the JSON. You’ll need to conform with the Display Requirements in order to display the Tweets on the site.


Thanks, is there any quick start guides or anything? I’m completely lost on how I start requesting the data from the JSON response though. My JavaScript is a little hit and miss but I’m handy with a bit of PHP. Just not sure how to go about requesting the data properly.

I’ve read old StackOverflow questions that say all API endpoints needs authentication now. I take it that’s the OAuth thing? A guide for newbies to the Twitter stack would be a treat if you guys have anything in the works. The current docs are a bit high-level… for me anyway.


This is a great idea. We don’t have any of our own tutorials currently, but we should definitely look into that.

Again, if you just want to embed Tweets into your site, you won’t need to worry about OAuth and authentication, as the widgets “just work”.

If you’re looking to use PHP and do your own integration, you might want to look at a library such as Abraham’s TwitterOAuth, or CodebirdPHP. There are some good tutorials around for those and I think both libraries have samples too.


Okay I’ll look into that, thanks. Yeah it’d be great to have a really dumbed down beginners guide because it’s going over my head a bit. I’d really like to write my own web app to pull my Tweets through really; for the experience and also so I can customise the look of them rather than having the default design.

I’ve set up an app but I’m kind of lost on what JSON URL I need to get the data and how I authenticate with the API.

I don’t want to give up on this though, if I can get it working it’s be a great success for me.


Hi Daniel, thanks for asking!

So you want to load Tweets from a certain user into your website? Sounds cool.
As Andy already stated, it might be the easiest to try out one of the pre-made widgets. They take care of displaying the Tweets appropriately (confirming the Display Requirements etc.), so this will be the least-effort way for you.

Once you’ve read the docs and are still convinced you’d like to go the manual way, get yourself an App with read-only access at You’ll end up with an OAuth consumer key (it represents the app) and a secret (that you should keep secret). Then, open the App editing page (click your App name on and generate an OAuth token for yourself. This will be the easiest way of accessing your own Tweets without going through the authentication flow.

Next, you’d want to download a copy of a Twitter library for PHP. For this sample, I’ll use Codebird-PHP, but it should be similar with any other library.

Then, include the library in your script and have it fetch what you want to access:

// you will get all of these at
define('TWITTER_OAUTH_CONSUMER_KEY', 'YourSecretKeyHere');
define('TWITTER_OAUTH_CONSUMER_SECRET', 'YourSecretSecretHere');
define('TWITTER_OAUTH_TOKEN', '12345-SomeVeryLongTokenWithADashInside');
define('TWITTER_OAUTH_TOKEN_SECRET', 'OneSecretMore');

// include the library, PHP 5.5+ required!
require_once 'libraries/codebird/src/codebird.php';

// make it aware of your OAuth app key

// now get an instance of the class
$cb = \Codebird\Codebird::getInstance();

// tell the library who you are

// scroll down to read the rest of this sample code

// set the user name to fetch tweets for
define('TWITTER_TIMELINE_USER', 'LarryMcTweet'); // without the @ sign

// load the tweets
$reply = $cb->statuses_userTimeline([
  'screen_name' => TWITTER_TIMELINE_USER

// check if reply was okay
if ($reply->httpstatus === 200) { // HTTP 200 is OK
  // forget the httpstatus and rate limiting fields

  // all the tweets are in the reply now
  foreach ($reply as $tweet) {
    echo $tweet->text;

When you want to find out what fields are included in a Tweet, check out the Tweet object reference.

Now, take into account how many users are visiting your website. Take a look at the rate-limiting section of the developer docs. Then, decide if you want to cache the Twitter API response for like 5 or 15 minutes so you won’t run over your limit.


The main challenge for us (at Twitter) is that the majority of the third-party client libraries for the API are not directly supported by us, so it gets complicated, which is why I suggested looking at the samples. I do understand the interest and desire for a simplified flow though, so we take that on board. Thanks!


Thanks for that sample jublonet, very helpful! My main struggle was making sure that all the data from the Tweets was being pulled through correctly from Twitter, I’ll take a look at Codebird-PHP though. I guess that’s my best option for right now anyway.

I understand. Perhaps you could look into supporting your own library in the future? An open source one that lets people of all abilities dabble and improve. Who knows, you might get your next lead engineer who started off tinkering around with the code… :slightly_smiling:

Either way, I appreciate the help guys. A lot more progress made here in the past few days than I’ve had for the past weeks trawling over the internet!


You make us really happy, Daniel. Glad we could help! :grinning: