API Documentation

• Getting Started

  The first thing you need to get started with the Cadmus API is your API key. You can get your API key from here. This key is used when making a call to the API and helps us identify who is making the call. You can also give your API key to third party applications and they can make the calls on your behalf. If at any point you feel that your key is being misused, you can simply reset the key here.

• Application Developers

  If you are an application developer and are looking to add Cadmus to your application then you can contact us via email or Twitter to get your application key. With this key and the Authentication API you can allow your users to seamlessly sign in with Cadmus and get their API key.

• Notes

  • Request parameters that are in bold are required parameters.
  • The HTTP status code of an error response corresponds to the error code. So if the error code is 401, the response header status would be 401 as well.
  • All our APIs that return JSON, support a pretty print flag. So by setting the format to be json and setting pretty to true you would get a more readable output. Here is an example: http://www.thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=json&pretty=true

• General API Methods

• posts
• posts/:hours
• verify_key
• auth/twitter

• • Twitter API Methods

  • twitter/statuses
  • twitter/statuses/:hours
  • twitter/links
  • twitter/related
  • twitter/comments
  • twitter/trends
  • twitter/search
  • twitter/lists/statuses/:hours
  • twitter/lists/related
  • twitter/lists/trends
  • twitter/lists/search

• The Posts API

  Using the Posts API you can get your stream sorted by relevance.

  • URL

    • http://www.thecadmus.com/api/posts

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    • JSON

      [
        {
          "id":5127572787,
          "text":"Test post content #1.",
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "link":"http:\/\/twitter.com\/fanjiewang\/status\/5127572787",
          "type":"twitter",
          "user":{
            "screen_name":"fanjiewang",
            "name":"Frank Wang",
            "profile_image_url":"http:\/\/s.twimg.com\/image_bigger.png",
            "profile_url":"http:\/\/twitter.com\/fanjiewang"
          },
          "comments":[
            {
              "id":123
              "text":"content",
              "created_at":"Tue Oct 27 18:04:00 +0000 2009",
              "link":"http:\/\/twitter.com\/fanjiewang\/status\/123",
              "type":"twitter",
              "user":{
                "screen_name":"fanjiewang",
                "name":"Frank Wang",
                "profile_image_url":"http:\/\/s.twimg.com\/image.img",
                "profile_url":"http:\/\/twitter.com\/fanjiewang"
              }
            }
          ],
          "related":[
            {
              "id":5127572788,
              "text":"Test post content #2.",
              "created_at":"Tue Oct 27 18:02:00 +0000 2009",
              "link":"http:\/\/twitter.com\/fanjiewang\/status\/5127572788",
              "type":"twitter",
              "user":{
                "screen_name":"fanjiewang",
                "name":"Frank Wang",
                "profile_image_url":"http:\/\/s.twimg.com\/image_bigger.png",
                "profile_url":"http:\/\/twitter.com\/fanjiewang"
              },
              "comments":[
                {
                  "id":1234
                  "text":"content",
                  "created_at":"Tue Oct 27 18:04:00 +0000 2009",
                  "link":"http:\/\/twitter.com\/fanjiewang\/status\/1234",
                  "type":"twitter",
                  "user":{
                    "screen_name":"fanjiewang",
                    "name":"Frank Wang",
                    "profile_image_url":"http:\/\/s.twimg.com\/image.img",
                    "profile_url":"http:\/\/twitter.com\/fanjiewang"
                  }
                }
              ]
            }
          ]
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([post, post,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <posts>
        <post>
          <id>123</id>
          <text>content</text>
          <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
          <service_type>twitter</service_type>
          <link>http://twitter.com/fanjiewang/status/123</link>
          <user>
            <screen_name>fanjiewang</screen_name>
            <name>Frank Wang</name>
            <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
            <profile_url>http://twitter.com/fanjiewang</profile_url>
          </user>
          <comments>
            <comment>
              <id>123</id>
              <text>content</text>
              <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
              <service_type>twitter</service_type>
              <link>http://twitter.com/fanjiewang/status/123</link>
              <user>
                <screen_name>fanjiewang</screen_name>
                <name>Frank Wang</name>
                <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
                <profile_url>http://twitter.com/fanjiewang</profile_url>
              </user>
            </comment>
          </comments>
          <related>
            <post>
              <id>1234</id>
              <text>content</text>
              <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
              <service_type>twitter</service_type>
              <link>http://twitter.com/fanjiewang/status/1234</link>
              <user>
                <screen_name>fanjiewang</screen_name>
                <name>Frank Wang</name>
                <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
                <profile_url>http://twitter.com/fanjiewang</profile_url>
              </user>
              <comments>
                <comment>
                  <id>123</id>
                  <text>content</text>
                  <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
                  <service_type>twitter</service_type>
                  <link>http://twitter.com/fanjiewang/status/123</link>
                  <user>
                    <screen_name>fanjiewang</screen_name>
                    <name>Frank Wang</name>
                    <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
                    <profile_url>http://twitter.com/fanjiewang</profile_url>
                  </user>
                </comment>
              </comments>
            </post>
          </related>
        </post>
        ... and so on ...
      </posts>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Default

      curl http://www.thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts

      curl http://www.thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Get the second page of posts

      curl http://www.thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2

    • Using a callback

      curl http://www.thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction

    • In XML

      curl http://www.thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&format=json&callback=showPostsFunction

• The Trending Posts API

  Using the Trending Posts API you can get the top posts in the last number of hours. The URL is made up of the number of hours (:hours) and is capped at 168 (1 week).

  • URL

    • http://www.thecadmus.com/api/posts/:hours

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    • JSON

      [
        {
          "id":5127572787,
          "text":"Test post content #1.",
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "link":"http:\/\/twitter.com\/fanjiewang\/status\/5127572787",
          "type":"twitter",
          "user":{
            "screen_name":"fanjiewang",
            "name":"Frank Wang",
            "profile_image_url":"http:\/\/s.twimg.com\/image_bigger.png",
            "profile_url":"http:\/\/twitter.com\/fanjiewang"
          },
          "comments":[
            {
              "id":123
              "text":"content",
              "created_at":"Tue Oct 27 18:04:00 +0000 2009",
              "link":"http:\/\/twitter.com\/fanjiewang\/status\/123",
              "type":"twitter",
              "user":{
                "screen_name":"fanjiewang",
                "name":"Frank Wang",
                "profile_image_url":"http:\/\/s.twimg.com\/image.img",
                "profile_url":"http:\/\/twitter.com\/fanjiewang"
              }
            }
          ],
          "related":[
            {
              "id":5127572788,
              "text":"Test post content #2.",
              "created_at":"Tue Oct 27 18:02:00 +0000 2009",
              "link":"http:\/\/twitter.com\/fanjiewang\/status\/5127572788",
              "type":"twitter",
              "user":{
                "screen_name":"fanjiewang",
                "name":"Frank Wang",
                "profile_image_url":"http:\/\/s.twimg.com\/image_bigger.png",
                "profile_url":"http:\/\/twitter.com\/fanjiewang"
              },
              "comments":[
                {
                  "id":1234
                  "text":"content",
                  "created_at":"Tue Oct 27 18:04:00 +0000 2009",
                  "link":"http:\/\/twitter.com\/fanjiewang\/status\/1234",
                  "type":"twitter",
                  "user":{
                    "screen_name":"fanjiewang",
                    "name":"Frank Wang",
                    "profile_image_url":"http:\/\/s.twimg.com\/image.img",
                    "profile_url":"http:\/\/twitter.com\/fanjiewang"
                  }
                }
              ]
            }
          ]
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([post, post,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <posts>
        <post>
          <id>123</id>
          <text>content</text>
          <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
          <service_type>twitter</service_type>
          <link>http://twitter.com/fanjiewang/status/123</link>
          <user>
            <screen_name>fanjiewang</screen_name>
            <name>Frank Wang</name>
            <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
            <profile_url>http://twitter.com/fanjiewang</profile_url>
          </user>
          <comments>
            <comment>
              <id>123</id>
              <text>content</text>
              <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
              <service_type>twitter</service_type>
              <link>http://twitter.com/fanjiewang/status/123</link>
              <user>
                <screen_name>fanjiewang</screen_name>
                <name>Frank Wang</name>
                <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
                <profile_url>http://twitter.com/fanjiewang</profile_url>
              </user>
            </comment>
          </comments>
          <related>
            <post>
              <id>1234</id>
              <text>content</text>
              <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
              <service_type>twitter</service_type>
              <link>http://twitter.com/fanjiewang/status/1234</link>
              <user>
                <screen_name>fanjiewang</screen_name>
                <name>Frank Wang</name>
                <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
                <profile_url>http://twitter.com/fanjiewang</profile_url>
              </user>
              <comments>
                <comment>
                  <id>123</id>
                  <text>content</text>
                  <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
                  <service_type>twitter</service_type>
                  <link>http://twitter.com/fanjiewang/status/123</link>
                  <user>
                    <screen_name>fanjiewang</screen_name>
                    <name>Frank Wang</name>
                    <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
                    <profile_url>http://twitter.com/fanjiewang</profile_url>
                  </user>
                </comment>
              </comments>
            </post>
          </related>
        </post>
        ... and so on ...
      </posts>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Get the posts in the past 10 hours

      curl http://www.thecadmus.com/api/posts/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts in the past 10 hours

      curl http://www.thecadmus.com/api/posts/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Get the second page of posts in the past 10 hours

      curl http://www.thecadmus.com/api/posts/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2

    • Using a callback

      curl http://www.thecadmus.com/api/posts/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction

    • In XML

      curl http://www.thecadmus.com/api/posts/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/posts/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&format=json&callback=showPostsFunction

• The Verify Key API

  Using this API, applications can verify if the given API key is valid. If the API key is valid then the associated user object is returned.

  • URL

    • http://www.thecadmus.com/api/verify_key

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • appkey

      The application key. You can contact us via email or via Twitter for for your application key.

  • Response

    • JSON

      {
        "username":"fanjiewang",
        "first_name":"Frank",
        "last_name":"Wang",
        "profile_image_url":"http:\/\/s.twimg.com\/image_bigger.png"
      }						

    • JSON with callback

      myCallbackFunction({
        "username":"fanjiewang",
        "first_name":"Frank",
        "last_name":"Wang",
        "profile_image_url":"http:\/\/s.twimg.com\/image_bigger.png"
      });						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <user>
        <username>fanjiewang</username>
        <first_name>Frank</first_name>
        <last_name>Wang</last_name>
        <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
      </user>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 403

      The application key is invalid. Please check the application key and try again.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL. Make sure the 'xxxx....' value is replaced with your real application key and API key.

    • Default

      curl http://www.thecadmus.com/verify_key?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&appkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

• The Twitter Auth API

  Using the Auth API you can allow a user to authenticate with Cadmus and get their API key. We use OAuth echo to verify the user's credentials with Twitter. If the user is successfully authenticated and the user has a Cadmus account we return the user's API key. If the user does not have a Cadmus account then we return a Twitter OAuth authorization URL for Cadmus. Upon completing the OAuth process we return the API key for the new user using the callback URL. The flow for the authentication process is shown below. For testing purposes this API takes a debug parameter. When set to true we assume that the authenticating user does not have a Cadmus account (even if he/she might) and return the auth_url. This allows you to test the flow without having to continually use new Twitter accounts to test. For example, http://www.thecadmus.com/api/auth/twitter?appkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&debug=true

  • URL

    • http://www.thecadmus.com/api/auth/twitter

  • Parameters

    This resource only accepts GET requests.

    • X-AUTH-SERVICE-PROVIDER

      The realm of the identity delegation; in the case of Twitter it is https://api.twitter.com/1/account/verify_credentials.json or http://api.twitter.com/1/account/verify_credentials.json depending on what you are using to sign the oauth_signature. This needs to be passed in the request header.
    • X-VERIFY-CREDENTIALS-AUTHORIZATION

      All the OAuth parameters necessary so we could call https://api.twitter.com/1/account/verify_credentials.json using OAuth in the HTTP header. For example it should look like: OAuth oauth_timestamp="1280175628", oauth_version="1.0", oauth_consumer_key="xxxxxxxxxxx", oauth_token="xxxxxxxxxxxx", oauth_signature="xxxxxxxxxxxxx", oauth_nonce="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", oauth_signature_method="HMAC-SHA1". For more information on Twitter OAuth parameters have a look at the Twitter OAuth documentation. This needs to be passed in the request header.
    • appkey

      The application key. You can contact us via email or via Twitter for for your application key.
    • callback_url

      For new Cadmus users that go through the Twitter OAuth authorization process we return their API key by calling back on this URL. Defaults to no value
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    • JSON

      {"key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}						

    • JSON with callback

      myCallbackFunction({"key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"});						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <auth>
        <key>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</key>
      </auth>						

    • Callback URL Request

      http://example.com/mycallback?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx						

    • 501 Error in JSON

      {
        "error":true,
        "code":501,
        "auth_url""https:\/\/api.twitter.com\/oauth\/authenticate?..."
      }						

    • 501 Error in JSON with callback

      myCallbackFunction({
        "error":true,
        "code":xxx,
        "auth_url""https:\/\/api.twitter.com\/oauth\/authenticate?..."
      });						

    • 501 Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
        <auth_url>https://api.twitter.com/oauth/authenticate?...</auth_url>
      </response>						

    • Callback URL Error Request

      http://example.com/mycallback?error=true&code=xxx						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      Authentication has failed. The oauth verification credentials given are invalid.

    • 403

      The application key is invalid. Please check the application key and try again.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

    • 501

      The given user is not a Cadmus user. Use the auth_url that is returned with the response to direct the user to sign in with Twitter and add Cadmus. After the user goes through the OAuth process we will pass their API key back through to the callback_url that was initially specified.

  • Examples

    You can try the examples below in your terminal using cURL. Make sure to replace x_auth_service_provider and x_verify_credentials_authorization with the real values. And the 'xxxx....' value needs to be replaced with your real application key.

    • Default

      curl -H "X-AUTH-SERVICE-PROVIDER: x_auth_service_provider" -H "X-VERIFY-CREDENTIALS-AUTHORIZATION: x_verify_credentials_authorization" http://www.thecadmus.com/api/auth/twitter?appkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Using a callback URL

      curl -H "X-AUTH-SERVICE-PROVIDER: x_auth_service_provider" -H "X-VERIFY-CREDENTIALS-AUTHORIZATION: x_verify_credentials_authorization" http://www.thecadmus.com/api/auth/twitter?appkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback_url=http%3A%2F%2Fexample.com%2Fmycallback

    • Using a callback

      curl -H "X-AUTH-SERVICE-PROVIDER: x_auth_service_provider" -H "X-VERIFY-CREDENTIALS-AUTHORIZATION: x_verify_credentials_authorization" http://www.thecadmus.com/api/auth/twitter?appkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=handleAuthFunction

    • In XML

      curl -H "X-AUTH-SERVICE-PROVIDER: x_auth_service_provider" -H "X-VERIFY-CREDENTIALS-AUTHORIZATION: x_verify_credentials_authorization" http://www.thecadmus.com/api/auth/twitter?appkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • All options

      curl -H "X-AUTH-SERVICE-PROVIDER: x_auth_service_provider" -H "X-VERIFY-CREDENTIALS-AUTHORIZATION: x_verify_credentials_authorization" http://www.thecadmus.com/api/auth/twitter?appkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=handleAuthFunction&callback_url=http%3A%2F%2Fexample.com%2Fmycallback

• The Twitter Statuses API

  Using the Twitter Statuses API you can get your Twitter home timeline sorted by relevance.

  • URL

    • http://www.thecadmus.com/api/twitter/statuses

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    Note: The related_count and comment_count values are added to the status.

    • JSON

      [
        {
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "geo":null,
          "in_reply_to_status_id":null,
          "place":null,
          "truncated":false,
          "source":"",
          "in_reply_to_user_id":null,
          "contributors":null,
          "coordinates":null,
          "user":{
            "profile_background_tile":false,
            "created_at":"Wed Mar 07 01:27:09 +0000 2007",
            "friends_count":699,
            "description":"Breaking Technology News And Opinions From TechCrunch",
            "statuses_count":16144,
            "profile_link_color":"0084B4",
            "following":null,
            "favourites_count":29,
            "contributors_enabled":false,
            "profile_sidebar_fill_color":"DDFFCC",
            "url":"http://www.techcrunch.com",
            "profile_image_url":"http://a3.twimg.com/bigger_normal.png",
            "geo_enabled":false,
            "notifications":false,
            "time_zone":"Pacific Time (US & Canada)",
            "profile_sidebar_border_color":"BDDCAD",
            "location":"Silicon Valley",
            "screen_name":"TechCrunch",
            "verified":false,
            "protected":false,
            "profile_background_color":"9AE4E8",
            "name":"TechCrunch",
            "profile_background_image_url":"http://twimg.com/bg.png",
            "followers_count":1366685,
            "id":816653,
            "lang":"en",
            "utc_offset":-28800,
            "profile_text_color":"333333"
          },
          "favorited":false,
          "id":12468685711,
          "in_reply_to_screen_name":null,
          "text":"Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ",
          "related_count":9,
          "comment_count":0
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([status, status,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <statuses>
        <status>
          <created_at>Mon Apr 19 18:11:29 +0000 2010</created_at>
          <geo></geo>
          <in_reply_to_status_id></in_reply_to_status_id>
          <place></place>
          <truncated></truncated>
          <source></source>
          <in_reply_to_user_id></in_reply_to_user_id>
          <contributors></contributors>
          <coordinates></coordinates>
          <user>
            <profile_background_tile></profile_background_tile>
            <created_at>Wed Mar 07 01:27:09 +0000 2007</created_at>
            <friends_count>699</friends_count>
            <description>Breaking Technology News And Opinions From TechCrunch</description>
            <statuses_count>16144</statuses_count>
            <profile_link_color>0084B4</profile_link_color>
            <following></following>
            <favourites_count>29</favourites_count>
            <contributors_enabled></contributors_enabled>
            <profile_sidebar_fill_color>DDFFCC</profile_sidebar_fill_color>
            <url>http://www.techcrunch.com</url>
            <profile_image_url>http://a3.twimg.com/bigger_normal.png</profile_image_url>
            <geo_enabled></geo_enabled>
            <notifications></notifications>
            <time_zone>Pacific Time (US & Canada)</time_zone>
            <profile_sidebar_border_color>BDDCAD</profile_sidebar_border_color>
            <location>Silicon Valley</location>
            <screen_name>TechCrunch</screen_name>
            <verified></verified>
            <protected></protected>
            <profile_background_color>9AE4E8</profile_background_color>
            <name>TechCrunch</name>
            <profile_background_image_url>http://twimg.com/bg.png</profile_background_image_url>
            <followers_count>1366685</followers_count>
            <id>816653</id>
            <lang>en</lang>
            <utc_offset>-28800</utc_offset>
            <profile_text_color>333333</profile_text_color>
          </user>
          <favorited></favorited>
          <id>12468685711</id>
          <in_reply_to_screen_name></in_reply_to_screen_name>
          <text>Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ</text>
          <related_count>9</related_count>
          <comment_count>0</comment_count>
        </status>
        ... and so on ...
      </statuses>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Default

      curl http://www.thecadmus.com/api/twitter/statuses?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts

      curl http://www.thecadmus.com/api/twitter/statuses?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Get the second page of posts

      curl http://www.thecadmus.com/api/twitter/statuses?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/statuses?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction

    • In XML

      curl http://www.thecadmus.com/api/twitter/statuses?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/twitter/statuses?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&format=json&callback=showPostsFunction

• The Trending Twitter Statuses API

  Using the Twitter Trending Statuses API you can get the top statuses in the last number of hours. The URL is made up of the number of hours (:hours) and is capped at 168 (1 week).

  • URL

    • http://www.thecadmus.com/api/twitter/statuses/:hours

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    Note: The related_count and comment_count values are added to the status.

    • JSON

      [
        {
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "geo":null,
          "in_reply_to_status_id":null,
          "place":null,
          "truncated":false,
          "source":"",
          "in_reply_to_user_id":null,
          "contributors":null,
          "coordinates":null,
          "user":{
            "profile_background_tile":false,
            "created_at":"Wed Mar 07 01:27:09 +0000 2007",
            "friends_count":699,
            "description":"Breaking Technology News And Opinions From TechCrunch",
            "statuses_count":16144,
            "profile_link_color":"0084B4",
            "following":null,
            "favourites_count":29,
            "contributors_enabled":false,
            "profile_sidebar_fill_color":"DDFFCC",
            "url":"http://www.techcrunch.com",
            "profile_image_url":"http://a3.twimg.com/bigger_normal.png",
            "geo_enabled":false,
            "notifications":false,
            "time_zone":"Pacific Time (US & Canada)",
            "profile_sidebar_border_color":"BDDCAD",
            "location":"Silicon Valley",
            "screen_name":"TechCrunch",
            "verified":false,
            "protected":false,
            "profile_background_color":"9AE4E8",
            "name":"TechCrunch",
            "profile_background_image_url":"http://twimg.com/bg.png",
            "followers_count":1366685,
            "id":816653,
            "lang":"en",
            "utc_offset":-28800,
            "profile_text_color":"333333"
          },
          "favorited":false,
          "id":12468685711,
          "in_reply_to_screen_name":null,
          "text":"Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ",
          "related_count":9,
          "comment_count":0
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([status, status,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <statuses>
        <status>
          <created_at>Mon Apr 19 18:11:29 +0000 2010</created_at>
          <geo></geo>
          <in_reply_to_status_id></in_reply_to_status_id>
          <place></place>
          <truncated></truncated>
          <source></source>
          <in_reply_to_user_id></in_reply_to_user_id>
          <contributors></contributors>
          <coordinates></coordinates>
          <user>
            <profile_background_tile></profile_background_tile>
            <created_at>Wed Mar 07 01:27:09 +0000 2007</created_at>
            <friends_count>699</friends_count>
            <description>Breaking Technology News And Opinions From TechCrunch</description>
            <statuses_count>16144</statuses_count>
            <profile_link_color>0084B4</profile_link_color>
            <following></following>
            <favourites_count>29</favourites_count>
            <contributors_enabled></contributors_enabled>
            <profile_sidebar_fill_color>DDFFCC</profile_sidebar_fill_color>
            <url>http://www.techcrunch.com</url>
            <profile_image_url>http://a3.twimg.com/bigger_normal.png</profile_image_url>
            <geo_enabled></geo_enabled>
            <notifications></notifications>
            <time_zone>Pacific Time (US & Canada)</time_zone>
            <profile_sidebar_border_color>BDDCAD</profile_sidebar_border_color>
            <location>Silicon Valley</location>
            <screen_name>TechCrunch</screen_name>
            <verified></verified>
            <protected></protected>
            <profile_background_color>9AE4E8</profile_background_color>
            <name>TechCrunch</name>
            <profile_background_image_url>http://twimg.com/bg.png</profile_background_image_url>
            <followers_count>1366685</followers_count>
            <id>816653</id>
            <lang>en</lang>
            <utc_offset>-28800</utc_offset>
            <profile_text_color>333333</profile_text_color>
          </user>
          <favorited></favorited>
          <id>12468685711</id>
          <in_reply_to_screen_name></in_reply_to_screen_name>
          <text>Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ</text>
          <related_count>9</related_count>
          <comment_count>0</comment_count>
        </status>
        ... and so on ...
      </statuses>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Get the posts in the past 10 hours

      curl http://www.thecadmus.com/api/twitter/statuses/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts in the past 10 hours

      curl http://www.thecadmus.com/api/twitter/statuses/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Get the second page of posts in the past 10 hours

      curl http://www.thecadmus.com/api/twitter/statuses/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/statuses/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction

    • In XML

      curl http://www.thecadmus.com/api/twitter/statuses/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/twitter/statuses?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&format=json&callback=showPostsFunction

• The Twitter Link Statuses API

  Using the Twitter Link Statuses API you can get the statuses in your Twitter home timeline that contain a link sorted by relevance.

  • URL

    • http://www.thecadmus.com/api/twitter/links

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    Note: The related_count and comment_count values are added to the status.

    • JSON

      [
        {
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "geo":null,
          "in_reply_to_status_id":null,
          "place":null,
          "truncated":false,
          "source":"",
          "in_reply_to_user_id":null,
          "contributors":null,
          "coordinates":null,
          "user":{
            "profile_background_tile":false,
            "created_at":"Wed Mar 07 01:27:09 +0000 2007",
            "friends_count":699,
            "description":"Breaking Technology News And Opinions From TechCrunch",
            "statuses_count":16144,
            "profile_link_color":"0084B4",
            "following":null,
            "favourites_count":29,
            "contributors_enabled":false,
            "profile_sidebar_fill_color":"DDFFCC",
            "url":"http://www.techcrunch.com",
            "profile_image_url":"http://a3.twimg.com/bigger_normal.png",
            "geo_enabled":false,
            "notifications":false,
            "time_zone":"Pacific Time (US & Canada)",
            "profile_sidebar_border_color":"BDDCAD",
            "location":"Silicon Valley",
            "screen_name":"TechCrunch",
            "verified":false,
            "protected":false,
            "profile_background_color":"9AE4E8",
            "name":"TechCrunch",
            "profile_background_image_url":"http://twimg.com/bg.png",
            "followers_count":1366685,
            "id":816653,
            "lang":"en",
            "utc_offset":-28800,
            "profile_text_color":"333333"
          },
          "favorited":false,
          "id":12468685711,
          "in_reply_to_screen_name":null,
          "text":"Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ",
          "related_count":9,
          "comment_count":0
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([status, status,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <statuses>
        <status>
          <created_at>Mon Apr 19 18:11:29 +0000 2010</created_at>
          <geo></geo>
          <in_reply_to_status_id></in_reply_to_status_id>
          <place></place>
          <truncated></truncated>
          <source></source>
          <in_reply_to_user_id></in_reply_to_user_id>
          <contributors></contributors>
          <coordinates></coordinates>
          <user>
            <profile_background_tile></profile_background_tile>
            <created_at>Wed Mar 07 01:27:09 +0000 2007</created_at>
            <friends_count>699</friends_count>
            <description>Breaking Technology News And Opinions From TechCrunch</description>
            <statuses_count>16144</statuses_count>
            <profile_link_color>0084B4</profile_link_color>
            <following></following>
            <favourites_count>29</favourites_count>
            <contributors_enabled></contributors_enabled>
            <profile_sidebar_fill_color>DDFFCC</profile_sidebar_fill_color>
            <url>http://www.techcrunch.com</url>
            <profile_image_url>http://a3.twimg.com/bigger_normal.png</profile_image_url>
            <geo_enabled></geo_enabled>
            <notifications></notifications>
            <time_zone>Pacific Time (US & Canada)</time_zone>
            <profile_sidebar_border_color>BDDCAD</profile_sidebar_border_color>
            <location>Silicon Valley</location>
            <screen_name>TechCrunch</screen_name>
            <verified></verified>
            <protected></protected>
            <profile_background_color>9AE4E8</profile_background_color>
            <name>TechCrunch</name>
            <profile_background_image_url>http://twimg.com/bg.png</profile_background_image_url>
            <followers_count>1366685</followers_count>
            <id>816653</id>
            <lang>en</lang>
            <utc_offset>-28800</utc_offset>
            <profile_text_color>333333</profile_text_color>
          </user>
          <favorited></favorited>
          <id>12468685711</id>
          <in_reply_to_screen_name></in_reply_to_screen_name>
          <text>Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ</text>
          <related_count>9</related_count>
          <comment_count>0</comment_count>
        </status>
        ... and so on ...
      </statuses>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Default

      curl http://www.thecadmus.com/api/twitter/links?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts

      curl http://www.thecadmus.com/api/twitter/links?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Get the second page of posts

      curl http://www.thecadmus.com/api/twitter/links?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/links?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction

    • In XML

      curl http://www.thecadmus.com/api/twitter/links?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/twitter/links?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&format=json&callback=showPostsFunction

• The Twitter Related Statuses API

  Using the Twitter Related Statuses API you can get a list of all the related statuses for a given status id. The URL is made up of the Twitter status id (:status).

  • URL

    • http://www.thecadmus.com/api/twitter/related/:status

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    Note: The related_count and comment_count values are added to the status. For related statuses the related_count is always 0.

    • JSON

      [
        {
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "geo":null,
          "in_reply_to_status_id":null,
          "place":null,
          "truncated":false,
          "source":"",
          "in_reply_to_user_id":null,
          "contributors":null,
          "coordinates":null,
          "user":{
            "profile_background_tile":false,
            "created_at":"Wed Mar 07 01:27:09 +0000 2007",
            "friends_count":699,
            "description":"Breaking Technology News And Opinions From TechCrunch",
            "statuses_count":16144,
            "profile_link_color":"0084B4",
            "following":null,
            "favourites_count":29,
            "contributors_enabled":false,
            "profile_sidebar_fill_color":"DDFFCC",
            "url":"http://www.techcrunch.com",
            "profile_image_url":"http://a3.twimg.com/bigger_normal.png",
            "geo_enabled":false,
            "notifications":false,
            "time_zone":"Pacific Time (US & Canada)",
            "profile_sidebar_border_color":"BDDCAD",
            "location":"Silicon Valley",
            "screen_name":"TechCrunch",
            "verified":false,
            "protected":false,
            "profile_background_color":"9AE4E8",
            "name":"TechCrunch",
            "profile_background_image_url":"http://twimg.com/bg.png",
            "followers_count":1366685,
            "id":816653,
            "lang":"en",
            "utc_offset":-28800,
            "profile_text_color":"333333"
          },
          "favorited":false,
          "id":12468685711,
          "in_reply_to_screen_name":null,
          "text":"Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ",
          "related_count":0,
          "comment_count":0
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([status, status,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <statuses>
        <status>
          <created_at>Mon Apr 19 18:11:29 +0000 2010</created_at>
          <geo></geo>
          <in_reply_to_status_id></in_reply_to_status_id>
          <place></place>
          <truncated></truncated>
          <source></source>
          <in_reply_to_user_id></in_reply_to_user_id>
          <contributors></contributors>
          <coordinates></coordinates>
          <user>
            <profile_background_tile></profile_background_tile>
            <created_at>Wed Mar 07 01:27:09 +0000 2007</created_at>
            <friends_count>699</friends_count>
            <description>Breaking Technology News And Opinions From TechCrunch</description>
            <statuses_count>16144</statuses_count>
            <profile_link_color>0084B4</profile_link_color>
            <following></following>
            <favourites_count>29</favourites_count>
            <contributors_enabled></contributors_enabled>
            <profile_sidebar_fill_color>DDFFCC</profile_sidebar_fill_color>
            <url>http://www.techcrunch.com</url>
            <profile_image_url>http://a3.twimg.com/bigger_normal.png</profile_image_url>
            <geo_enabled></geo_enabled>
            <notifications></notifications>
            <time_zone>Pacific Time (US & Canada)</time_zone>
            <profile_sidebar_border_color>BDDCAD</profile_sidebar_border_color>
            <location>Silicon Valley</location>
            <screen_name>TechCrunch</screen_name>
            <verified></verified>
            <protected></protected>
            <profile_background_color>9AE4E8</profile_background_color>
            <name>TechCrunch</name>
            <profile_background_image_url>http://twimg.com/bg.png</profile_background_image_url>
            <followers_count>1366685</followers_count>
            <id>816653</id>
            <lang>en</lang>
            <utc_offset>-28800</utc_offset>
            <profile_text_color>333333</profile_text_color>
          </user>
          <favorited></favorited>
          <id>12468685711</id>
          <in_reply_to_screen_name></in_reply_to_screen_name>
          <text>Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ</text>
          <related_count>0</related_count>
          <comment_count>0</comment_count>
        </status>
        ... and so on ...
      </statuses>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Default

      curl http://www.thecadmus.com/api/twitter/related/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts

      curl http://www.thecadmus.com/api/twitter/related/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Get the second page of posts

      curl http://www.thecadmus.com/api/twitter/related/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/related/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction

    • In XML

      curl http://www.thecadmus.com/api/twitter/related/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/twitter/related/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&format=json&callback=showPostsFunction

• The Twitter Comment Statuses API

  Using the Twitter Comment Statuses API you can get a list of all the comment statuses for a given status id. The URL is made up of the Twitter status id (:status).

  • URL

    • http://www.thecadmus.com/api/twitter/comments/:status

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    Note: The related_count and comment_count values are added to the status. For comment statuses the related_count and comment_count is always 0.

    • JSON

      [
        {
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "geo":null,
          "in_reply_to_status_id":null,
          "place":null,
          "truncated":false,
          "source":"",
          "in_reply_to_user_id":null,
          "contributors":null,
          "coordinates":null,
          "user":{
            "profile_background_tile":false,
            "created_at":"Wed Mar 07 01:27:09 +0000 2007",
            "friends_count":699,
            "description":"Breaking Technology News And Opinions From TechCrunch",
            "statuses_count":16144,
            "profile_link_color":"0084B4",
            "following":null,
            "favourites_count":29,
            "contributors_enabled":false,
            "profile_sidebar_fill_color":"DDFFCC",
            "url":"http://www.techcrunch.com",
            "profile_image_url":"http://a3.twimg.com/bigger_normal.png",
            "geo_enabled":false,
            "notifications":false,
            "time_zone":"Pacific Time (US & Canada)",
            "profile_sidebar_border_color":"BDDCAD",
            "location":"Silicon Valley",
            "screen_name":"TechCrunch",
            "verified":false,
            "protected":false,
            "profile_background_color":"9AE4E8",
            "name":"TechCrunch",
            "profile_background_image_url":"http://twimg.com/bg.png",
            "followers_count":1366685,
            "id":816653,
            "lang":"en",
            "utc_offset":-28800,
            "profile_text_color":"333333"
          },
          "favorited":false,
          "id":12468685711,
          "in_reply_to_screen_name":null,
          "text":"Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ",
          "related_count":0,
          "comment_count":0
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([status, status,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <statuses>
        <status>
          <created_at>Mon Apr 19 18:11:29 +0000 2010</created_at>
          <geo></geo>
          <in_reply_to_status_id></in_reply_to_status_id>
          <place></place>
          <truncated></truncated>
          <source></source>
          <in_reply_to_user_id></in_reply_to_user_id>
          <contributors></contributors>
          <coordinates></coordinates>
          <user>
            <profile_background_tile></profile_background_tile>
            <created_at>Wed Mar 07 01:27:09 +0000 2007</created_at>
            <friends_count>699</friends_count>
            <description>Breaking Technology News And Opinions From TechCrunch</description>
            <statuses_count>16144</statuses_count>
            <profile_link_color>0084B4</profile_link_color>
            <following></following>
            <favourites_count>29</favourites_count>
            <contributors_enabled></contributors_enabled>
            <profile_sidebar_fill_color>DDFFCC</profile_sidebar_fill_color>
            <url>http://www.techcrunch.com</url>
            <profile_image_url>http://a3.twimg.com/bigger_normal.png</profile_image_url>
            <geo_enabled></geo_enabled>
            <notifications></notifications>
            <time_zone>Pacific Time (US & Canada)</time_zone>
            <profile_sidebar_border_color>BDDCAD</profile_sidebar_border_color>
            <location>Silicon Valley</location>
            <screen_name>TechCrunch</screen_name>
            <verified></verified>
            <protected></protected>
            <profile_background_color>9AE4E8</profile_background_color>
            <name>TechCrunch</name>
            <profile_background_image_url>http://twimg.com/bg.png</profile_background_image_url>
            <followers_count>1366685</followers_count>
            <id>816653</id>
            <lang>en</lang>
            <utc_offset>-28800</utc_offset>
            <profile_text_color>333333</profile_text_color>
          </user>
          <favorited></favorited>
          <id>12468685711</id>
          <in_reply_to_screen_name></in_reply_to_screen_name>
          <text>Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ</text>
          <related_count>0</related_count>
          <comment_count>0</comment_count>
        </status>
        ... and so on ...
      </statuses>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Default

      curl http://www.thecadmus.com/api/twitter/comments/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts

      curl http://www.thecadmus.com/api/twitter/comments/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Get the second page of posts

      curl http://www.thecadmus.com/api/twitter/comments/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/comments/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction

    • In XML

      curl http://www.thecadmus.com/api/twitter/comments/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/twitter/comments/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&format=json&callback=showPostsFunction

• The Twitter Personal Trends API

  Using the Twitter Personal Trends API you can get a list of all your personal trending topics.

  • URL

    • http://www.thecadmus.com/api/twitter/trends

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of trends to return. Defaults to 10. Restricted to a maximum of 20.
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    • JSON

      {
        "trends":
        [  
          {
            "name":"iPhone",
            "query":"iPhone",
            "url":"http://thecadmus.com/#search?q=iPhone"
          },
          {
            "name":"Twitter",
            "query":"Twitter",
            "url":"http://thecadmus.com/#search?q=Twitter"
          },
          ... and so on ...
        ],
        "as_of":"Tue, 22 Jun 2010 17:19:03 +0000"
      }						

    • JSON with callback

      myCallbackFunction({
        "trends":[trend, trend,...],
        "as_of":"Tue, 22 Jun 2010 17:19:03 +0000"
      });						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <trends as_of="Tue, 22 Jun 2010 17:19:03 +0000">
        <trend>
          <name>iPhone</name>
          <query>iPhone</query>
          <url>http://thecadmus.com/#search?q=iPhone</url>
        </trend>
        <trend>
          <name>Twitter</name>
          <query>Twitter</query>
          <url>http://thecadmus.com/#search?q=Twitter</url>
        </trend>
        ... and so on ...
      </trends>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Default

      curl http://www.thecadmus.com/api/twitter/trends?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 trends

      curl http://www.thecadmus.com/api/twitter/trends?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/trends?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showTrendsFunction

    • In XML

      curl http://www.thecadmus.com/api/twitter/trends?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/twitter/trends?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10&format=json&callback=showTrendsFunction

• The Twitter Personal Search API

  Using the Twitter Personal Search API you can get your Twitter Statuses for a given query. Currently, we do not return results for queries that are not personal trending topics.

  • URL

    • http://www.thecadmus.com/api/twitter/search

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • query

      The search query. This has to be one of the personal trending topics as returned by twitter/trends.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    Note: The related_count and comment_count values are added to the status.

    • JSON

      [
        {
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "geo":null,
          "in_reply_to_status_id":null,
          "place":null,
          "truncated":false,
          "source":"",
          "in_reply_to_user_id":null,
          "contributors":null,
          "coordinates":null,
          "user":{
            "profile_background_tile":false,
            "created_at":"Wed Mar 07 01:27:09 +0000 2007",
            "friends_count":699,
            "description":"Breaking Technology News And Opinions From TechCrunch",
            "statuses_count":16144,
            "profile_link_color":"0084B4",
            "following":null,
            "favourites_count":29,
            "contributors_enabled":false,
            "profile_sidebar_fill_color":"DDFFCC",
            "url":"http://www.techcrunch.com",
            "profile_image_url":"http://a3.twimg.com/bigger_normal.png",
            "geo_enabled":false,
            "notifications":false,
            "time_zone":"Pacific Time (US & Canada)",
            "profile_sidebar_border_color":"BDDCAD",
            "location":"Silicon Valley",
            "screen_name":"TechCrunch",
            "verified":false,
            "protected":false,
            "profile_background_color":"9AE4E8",
            "name":"TechCrunch",
            "profile_background_image_url":"http://twimg.com/bg.png",
            "followers_count":1366685,
            "id":816653,
            "lang":"en",
            "utc_offset":-28800,
            "profile_text_color":"333333"
          },
          "favorited":false,
          "id":12468685711,
          "in_reply_to_screen_name":null,
          "text":"Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ",
          "related_count":0,
          "comment_count":0
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([status, status,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <statuses>
        <status>
          <created_at>Mon Apr 19 18:11:29 +0000 2010</created_at>
          <geo></geo>
          <in_reply_to_status_id></in_reply_to_status_id>
          <place></place>
          <truncated></truncated>
          <source></source>
          <in_reply_to_user_id></in_reply_to_user_id>
          <contributors></contributors>
          <coordinates></coordinates>
          <user>
            <profile_background_tile></profile_background_tile>
            <created_at>Wed Mar 07 01:27:09 +0000 2007</created_at>
            <friends_count>699</friends_count>
            <description>Breaking Technology News And Opinions From TechCrunch</description>
            <statuses_count>16144</statuses_count>
            <profile_link_color>0084B4</profile_link_color>
            <following></following>
            <favourites_count>29</favourites_count>
            <contributors_enabled></contributors_enabled>
            <profile_sidebar_fill_color>DDFFCC</profile_sidebar_fill_color>
            <url>http://www.techcrunch.com</url>
            <profile_image_url>http://a3.twimg.com/bigger_normal.png</profile_image_url>
            <geo_enabled></geo_enabled>
            <notifications></notifications>
            <time_zone>Pacific Time (US & Canada)</time_zone>
            <profile_sidebar_border_color>BDDCAD</profile_sidebar_border_color>
            <location>Silicon Valley</location>
            <screen_name>TechCrunch</screen_name>
            <verified></verified>
            <protected></protected>
            <profile_background_color>9AE4E8</profile_background_color>
            <name>TechCrunch</name>
            <profile_background_image_url>http://twimg.com/bg.png</profile_background_image_url>
            <followers_count>1366685</followers_count>
            <id>816653</id>
            <lang>en</lang>
            <utc_offset>-28800</utc_offset>
            <profile_text_color>333333</profile_text_color>
          </user>
          <favorited></favorited>
          <id>12468685711</id>
          <in_reply_to_screen_name></in_reply_to_screen_name>
          <text>Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ</text>
          <related_count>0</related_count>
          <comment_count>0</comment_count>
        </status>
        ... and so on ...
      </statuses>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Default

      curl http://www.thecadmus.com/api/twitter/search?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts

      curl http://www.thecadmus.com/api/twitter/search?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10&query=iPhone

    • Get the second page of posts

      curl http://www.thecadmus.com/api/twitter/search?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2&query=iPhone

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/search?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction&query=iPhone

    • In XML

      curl http://www.thecadmus.com/api/twitter/search?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml&query=iPhone

    • All options

      curl http://www.thecadmus.com/api/twitter/search?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&query=iPhone&format=json&callback=showPostsFunction

• The Trending Twitter List Statuses API

  Using the Twitter List Statuses API you can get the top Twitter statuses in the last number of hours from the lists you are subscribed to. The URL is made up of the Twitter username (:user), the list name (:list) and the number of hours (:hours) capped at 168 (1 week).

  • URL

    • http://www.thecadmus.com/api/twitter/lists/statuses/:user/:list/:hours

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    Note: The related_count and comment_count values are added to the status.

    • JSON

      [
        {
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "geo":null,
          "in_reply_to_status_id":null,
          "place":null,
          "truncated":false,
          "source":"",
          "in_reply_to_user_id":null,
          "contributors":null,
          "coordinates":null,
          "user":{
            "profile_background_tile":false,
            "created_at":"Wed Mar 07 01:27:09 +0000 2007",
            "friends_count":699,
            "description":"Breaking Technology News And Opinions From TechCrunch",
            "statuses_count":16144,
            "profile_link_color":"0084B4",
            "following":null,
            "favourites_count":29,
            "contributors_enabled":false,
            "profile_sidebar_fill_color":"DDFFCC",
            "url":"http://www.techcrunch.com",
            "profile_image_url":"http://a3.twimg.com/bigger_normal.png",
            "geo_enabled":false,
            "notifications":false,
            "time_zone":"Pacific Time (US & Canada)",
            "profile_sidebar_border_color":"BDDCAD",
            "location":"Silicon Valley",
            "screen_name":"TechCrunch",
            "verified":false,
            "protected":false,
            "profile_background_color":"9AE4E8",
            "name":"TechCrunch",
            "profile_background_image_url":"http://twimg.com/bg.png",
            "followers_count":1366685,
            "id":816653,
            "lang":"en",
            "utc_offset":-28800,
            "profile_text_color":"333333"
          },
          "favorited":false,
          "id":12468685711,
          "in_reply_to_screen_name":null,
          "text":"Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ",
          "related_count":9,
          "comment_count":0
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([status, status,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <statuses>
        <status>
          <created_at>Mon Apr 19 18:11:29 +0000 2010</created_at>
          <geo></geo>
          <in_reply_to_status_id></in_reply_to_status_id>
          <place></place>
          <truncated></truncated>
          <source></source>
          <in_reply_to_user_id></in_reply_to_user_id>
          <contributors></contributors>
          <coordinates></coordinates>
          <user>
            <profile_background_tile></profile_background_tile>
            <created_at>Wed Mar 07 01:27:09 +0000 2007</created_at>
            <friends_count>699</friends_count>
            <description>Breaking Technology News And Opinions From TechCrunch</description>
            <statuses_count>16144</statuses_count>
            <profile_link_color>0084B4</profile_link_color>
            <following></following>
            <favourites_count>29</favourites_count>
            <contributors_enabled></contributors_enabled>
            <profile_sidebar_fill_color>DDFFCC</profile_sidebar_fill_color>
            <url>http://www.techcrunch.com</url>
            <profile_image_url>http://a3.twimg.com/bigger_normal.png</profile_image_url>
            <geo_enabled></geo_enabled>
            <notifications></notifications>
            <time_zone>Pacific Time (US & Canada)</time_zone>
            <profile_sidebar_border_color>BDDCAD</profile_sidebar_border_color>
            <location>Silicon Valley</location>
            <screen_name>TechCrunch</screen_name>
            <verified></verified>
            <protected></protected>
            <profile_background_color>9AE4E8</profile_background_color>
            <name>TechCrunch</name>
            <profile_background_image_url>http://twimg.com/bg.png</profile_background_image_url>
            <followers_count>1366685</followers_count>
            <id>816653</id>
            <lang>en</lang>
            <utc_offset>-28800</utc_offset>
            <profile_text_color>333333</profile_text_color>
          </user>
          <favorited></favorited>
          <id>12468685711</id>
          <in_reply_to_screen_name></in_reply_to_screen_name>
          <text>Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ</text>
          <related_count>9</related_count>
          <comment_count>0</comment_count>
        </status>
        ... and so on ...
      </statuses>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Get the posts in the past 10 hours

      curl http://www.thecadmus.com/api/twitter/lists/statuses/thecadmus/technology/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts in the past 10 hours

      curl http://www.thecadmus.com/api/twitter/lists/statuses/thecadmus/technology/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Get the second page of posts in the past 10 hours

      curl http://www.thecadmus.com/api/twitter/lists/statuses/thecadmus/technology/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/lists/statuses/thecadmus/technology/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction

    • In XML

      curl http://www.thecadmus.com/api/twitter/lists/statuses/thecadmus/technology/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/twitter/lists/statuses/thecadmus/technology/10?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&format=json&callback=showPostsFunction

• The Twitter List Related Statuses API

  Using the Twitter List Related Statuses API you can get a list of all the related statuses for a given status id within a certain list. The URL is made up of the Twitter username (:user), list (:list) and status id (:status).

  • URL

    • http://www.thecadmus.com/api/twitter/lists/related/:user/:list/:status

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    Note: The related_count and comment_count values are added to the status. For related statuses the related_count is always 0.

    • JSON

      [
        {
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "geo":null,
          "in_reply_to_status_id":null,
          "place":null,
          "truncated":false,
          "source":"",
          "in_reply_to_user_id":null,
          "contributors":null,
          "coordinates":null,
          "user":{
            "profile_background_tile":false,
            "created_at":"Wed Mar 07 01:27:09 +0000 2007",
            "friends_count":699,
            "description":"Breaking Technology News And Opinions From TechCrunch",
            "statuses_count":16144,
            "profile_link_color":"0084B4",
            "following":null,
            "favourites_count":29,
            "contributors_enabled":false,
            "profile_sidebar_fill_color":"DDFFCC",
            "url":"http://www.techcrunch.com",
            "profile_image_url":"http://a3.twimg.com/bigger_normal.png",
            "geo_enabled":false,
            "notifications":false,
            "time_zone":"Pacific Time (US & Canada)",
            "profile_sidebar_border_color":"BDDCAD",
            "location":"Silicon Valley",
            "screen_name":"TechCrunch",
            "verified":false,
            "protected":false,
            "profile_background_color":"9AE4E8",
            "name":"TechCrunch",
            "profile_background_image_url":"http://twimg.com/bg.png",
            "followers_count":1366685,
            "id":816653,
            "lang":"en",
            "utc_offset":-28800,
            "profile_text_color":"333333"
          },
          "favorited":false,
          "id":12468685711,
          "in_reply_to_screen_name":null,
          "text":"Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ",
          "related_count":0,
          "comment_count":0
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([status, status,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <statuses>
        <status>
          <created_at>Mon Apr 19 18:11:29 +0000 2010</created_at>
          <geo></geo>
          <in_reply_to_status_id></in_reply_to_status_id>
          <place></place>
          <truncated></truncated>
          <source></source>
          <in_reply_to_user_id></in_reply_to_user_id>
          <contributors></contributors>
          <coordinates></coordinates>
          <user>
            <profile_background_tile></profile_background_tile>
            <created_at>Wed Mar 07 01:27:09 +0000 2007</created_at>
            <friends_count>699</friends_count>
            <description>Breaking Technology News And Opinions From TechCrunch</description>
            <statuses_count>16144</statuses_count>
            <profile_link_color>0084B4</profile_link_color>
            <following></following>
            <favourites_count>29</favourites_count>
            <contributors_enabled></contributors_enabled>
            <profile_sidebar_fill_color>DDFFCC</profile_sidebar_fill_color>
            <url>http://www.techcrunch.com</url>
            <profile_image_url>http://a3.twimg.com/bigger_normal.png</profile_image_url>
            <geo_enabled></geo_enabled>
            <notifications></notifications>
            <time_zone>Pacific Time (US & Canada)</time_zone>
            <profile_sidebar_border_color>BDDCAD</profile_sidebar_border_color>
            <location>Silicon Valley</location>
            <screen_name>TechCrunch</screen_name>
            <verified></verified>
            <protected></protected>
            <profile_background_color>9AE4E8</profile_background_color>
            <name>TechCrunch</name>
            <profile_background_image_url>http://twimg.com/bg.png</profile_background_image_url>
            <followers_count>1366685</followers_count>
            <id>816653</id>
            <lang>en</lang>
            <utc_offset>-28800</utc_offset>
            <profile_text_color>333333</profile_text_color>
          </user>
          <favorited></favorited>
          <id>12468685711</id>
          <in_reply_to_screen_name></in_reply_to_screen_name>
          <text>Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ</text>
          <related_count>0</related_count>
          <comment_count>0</comment_count>
        </status>
        ... and so on ...
      </statuses>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Default

      curl http://www.thecadmus.com/api/twitter/lists/related/thecadmus/technology/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts

      curl http://www.thecadmus.com/api/twitter/lists/related/thecadmus/technology/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Get the second page of posts

      curl http://www.thecadmus.com/api/twitter/lists/related/thecadmus/technology/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/lists/related/thecadmus/technology/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction

    • In XML

      curl http://www.thecadmus.com/api/twitter/lists/related/thecadmus/technology/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/twitter/lists/related/thecadmus/technology/1000000000?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&format=json&callback=showPostsFunction

• The Twitter List Trends API

  Using the Twitter List Trends API you can get a the trending topics from a list. The URL is made up of the Twitter username (:user) and the list name (:list).

  • URL

    • http://www.thecadmus.com/api/twitter/lists/trends/:user/:list

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • count

      The number of trends to return. Defaults to 10. Restricted to a maximum of 20
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    • JSON

      {
        "trends":
        [
          {
            "name":"iPhone",
            "query":"iPhone",
            "url":"http://thecadmus.com/lists/thecadmus/technology#search?q=iPhone"
          },
          {
            "name":"Twitter",
            "query":"Twitter",
            "url":"http://thecadmus.com/lists/thecadmus/technology#search?q=Twitter"
          },
          ... and so on ...
        ],
        "as_of":"Tue, 22 Jun 2010 17:19:03 +0000"
      }						

    • JSON with callback

      myCallbackFunction({
        "trends":[trend, trend,...],
        "as_of":"Tue, 22 Jun 2010 17:19:03 +0000"
      });						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <trends as_of="Tue, 22 Jun 2010 17:19:03 +0000">
        <trend>
          <name>iPhone</name>
          <query>iPhone</query>
          <url>http://thecadmus.com/lists/thecadmus/technology#search?q=iPhone</url>
        </trend>
        <trend>
          <name>Twitter</name>
          <query>Twitter</query>
          <url>http://thecadmus.com/lists/thecadmus/technology#search?q=Twitter</url>
        </trend>
        ... and so on ...
      </trends>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Default

      curl http://www.thecadmus.com/api/twitter/lists/trends/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 trends

      curl http://www.thecadmus.com/api/twitter/lists/trends/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/lists/trends/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showTrendsFunction

    • In XML

      curl http://www.thecadmus.com/api/twitter/lists/trends/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml

    • All options

      curl http://www.thecadmus.com/api/twitter/lists/trends/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10&format=json&callback=showTrendsFunction

• The Twitter List Search API

  Using the Twitter List Search API you can get your Twitter Statuses for a given query. Currently, we do not return results for queries that are not list trending topics. The URL is made up of the Twitter username (:user) and the list name (:list).

  • URL

    • http://www.thecadmus.com/api/twitter/lists/search/:user/:list

  • Parameters

    This resource only accepts GET requests.

    • key

      The API key. You can get your API key from here.
    • query

      The search query. This has to be one of the list trending topics as returned by twitter/lists/trends.
    • count

      The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
    • page

      The page number of the results. Defaults to 1 (the first page of posts).
    • format

      The format of the response (xml or json). Defaults to json.
    • callback

      The JSON callback function. Defaults to no value.

  • Response

    Note: The related_count and comment_count values are added to the status.

    • JSON

      [
        {
          "created_at":"Tue Oct 27 18:02:00 +0000 2009",
          "geo":null,
          "in_reply_to_status_id":null,
          "place":null,
          "truncated":false,
          "source":"",
          "in_reply_to_user_id":null,
          "contributors":null,
          "coordinates":null,
          "user":{
            "profile_background_tile":false,
            "created_at":"Wed Mar 07 01:27:09 +0000 2007",
            "friends_count":699,
            "description":"Breaking Technology News And Opinions From TechCrunch",
            "statuses_count":16144,
            "profile_link_color":"0084B4",
            "following":null,
            "favourites_count":29,
            "contributors_enabled":false,
            "profile_sidebar_fill_color":"DDFFCC",
            "url":"http://www.techcrunch.com",
            "profile_image_url":"http://a3.twimg.com/bigger_normal.png",
            "geo_enabled":false,
            "notifications":false,
            "time_zone":"Pacific Time (US & Canada)",
            "profile_sidebar_border_color":"BDDCAD",
            "location":"Silicon Valley",
            "screen_name":"TechCrunch",
            "verified":false,
            "protected":false,
            "profile_background_color":"9AE4E8",
            "name":"TechCrunch",
            "profile_background_image_url":"http://twimg.com/bg.png",
            "followers_count":1366685,
            "id":816653,
            "lang":"en",
            "utc_offset":-28800,
            "profile_text_color":"333333"
          },
          "favorited":false,
          "id":12468685711,
          "in_reply_to_screen_name":null,
          "text":"Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ",
          "related_count":0,
          "comment_count":0
        },
        ... and so on ...
      ]						

    • JSON with callback

      myCallbackFunction([status, status,...]);						

    • XML

      <?xml version="1.0" encoding="UTF-8"?>
      <statuses>
        <status>
          <created_at>Mon Apr 19 18:11:29 +0000 2010</created_at>
          <geo></geo>
          <in_reply_to_status_id></in_reply_to_status_id>
          <place></place>
          <truncated></truncated>
          <source></source>
          <in_reply_to_user_id></in_reply_to_user_id>
          <contributors></contributors>
          <coordinates></coordinates>
          <user>
            <profile_background_tile></profile_background_tile>
            <created_at>Wed Mar 07 01:27:09 +0000 2007</created_at>
            <friends_count>699</friends_count>
            <description>Breaking Technology News And Opinions From TechCrunch</description>
            <statuses_count>16144</statuses_count>
            <profile_link_color>0084B4</profile_link_color>
            <following></following>
            <favourites_count>29</favourites_count>
            <contributors_enabled></contributors_enabled>
            <profile_sidebar_fill_color>DDFFCC</profile_sidebar_fill_color>
            <url>http://www.techcrunch.com</url>
            <profile_image_url>http://a3.twimg.com/bigger_normal.png</profile_image_url>
            <geo_enabled></geo_enabled>
            <notifications></notifications>
            <time_zone>Pacific Time (US & Canada)</time_zone>
            <profile_sidebar_border_color>BDDCAD</profile_sidebar_border_color>
            <location>Silicon Valley</location>
            <screen_name>TechCrunch</screen_name>
            <verified></verified>
            <protected></protected>
            <profile_background_color>9AE4E8</profile_background_color>
            <name>TechCrunch</name>
            <profile_background_image_url>http://twimg.com/bg.png</profile_background_image_url>
            <followers_count>1366685</followers_count>
            <id>816653</id>
            <lang>en</lang>
            <utc_offset>-28800</utc_offset>
            <profile_text_color>333333</profile_text_color>
          </user>
          <favorited></favorited>
          <id>12468685711</id>
          <in_reply_to_screen_name></in_reply_to_screen_name>
          <text>Bill Gates Talks About How To Change The World - http://tcrn.ch/aXhQtZ</text>
          <related_count>0</related_count>
          <comment_count>0</comment_count>
        </status>
        ... and so on ...
      </statuses>						

    • Error in JSON

      {"error":true,"code":xxx}						

    • Error in JSON with callback

      myCallbackFunction({"error":true,"code":xxx});						

    • Error in XML

      <?xml version="1.0" encoding="UTF-8"?>
      <response>
        <error>true</error>
        <code>xxx</code>
      </response>						

  • Error Codes

    Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.

    • 400

      The request parameters are invalid. Please check the parameters that are being passed in.

    • 401

      The API key given is invalid. You can get the right API key from here.

    • 404

      The API resource does not exist. Check the API URL for typos.

    • 405

      The request method is not supported; for example, using POST when only GET is supported. Please check the request method that is used.

    • 500

      Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

  • Examples

    You can try the examples below in your terminal using cURL or simply put in the URL in your browser and try it out. The 'xxxx....' value needs to be replaced with your real API key, which you can find here.

    • Default

      curl http://www.thecadmus.com/api/twitter/lists/search/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    • Get 10 posts

      curl http://www.thecadmus.com/api/twitter/lists/search/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10&query=iPhone

    • Get the second page of posts

      curl http://www.thecadmus.com/api/twitter/lists/search/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2&query=iPhone

    • Using a callback

      curl http://www.thecadmus.com/api/twitter/lists/search/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction&query=iPhone

    • In XML

      curl http://www.thecadmus.com/api/twitter/lists/search/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml&query=iPhone

    • All options

      curl http://www.thecadmus.com/api/twitter/lists/search/thecadmus/technology?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1&query=iPhone&format=json&callback=showPostsFunction

This page was last updated on Sept 9, 2010.