Home

Contents

1. Upload and Embed
2. Search
3. Phantom User Accounts

Tutorials

These tutorials are meant to help developers get up-to-speed with the Scribd API by showing typical flows. Although the audience is expected to have at least some programming experience, we attempt to remain language agnostic. Check out the client libraries available to find a Scribd interface in your favorite language.

Since the examples in these tutorials require an HTTP client, we use curl for its availability on a large variety of platforms and ability to cleanly handle multipart/form-data (a point of complexity in many programming environments).

1. Upload and Embed

In this tutorial, we will use the docs.upload method to POST a document to Scribd and then embed it in an external site using the JavaScript API

First, upload a document. In this example we will use curl to POST a text file using multipart/form-data. To try out this example, simply replace <api_key> with your API key.

$ echo "This is a test." > test.txt
$ curl -F "file=test.txt;type=text/plain" \
  "api.scribd.com/api?method=docs.upload&api_key=<api_key>"

Example response:

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'>
  <doc_id>123456</doc_id>
  <access_key>key-rvfa2c82sq5bf9q8t6v</access_key>
</rsp>

Use the <doc_id> and <access_key> from the response to embed the document on an external site:

<script type='text/javascript' src='http://www.scribd.com/javascripts/scribd_api.js'></script&gt />

<div id='embed'><a href='http://www.scribd.com'>Scribd</a></div>

<script type='text/javascript'>
  var scribd_doc = scribd.Document.getDoc(123456, 'key-rvfa2c82sq5bf9q8t6v' );
  
  var onReady = function(e){
    scribd_doc.api.setPage(3);
  }
  
  scribd_doc.addParam( 'jsapi_version', 2 );
  scribd_doc.addEventListener('onReady', onReady);
  scribd_doc.write('embed');
</script>

2. Search

The docs.search API can be used to search all documents or just those owned by a single user.

For example, the following curl command searches all of Scribd for documents matching "ruby on rails":

$ curl "api.scribd.com/api?method=docs.search&api_key=<api_key>&query=ruby%20on%20rails&scope=all"

Example response (truncated):

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'>
  <result_set totalResultsAvailable='1000' totalResultsReturned='10' list='true' tResultPosition='1'>
    <result>
      <doc_id>12353499</doc_id>
      <access_key>key-1ymqejgjhhfvb0rfkx05</access_key>
      <title>
        <![CDATA[Ruby on Rails: A Simple Decision?]]>/>
      </title>
      <description>
        <![CDATA[Final project assignment for 2008 elor of Information Degree: Research into Ruby on Rails. ]]>
      </description>
      <tags>
        <![CDATA[arch,rails,ruby,agile,evaluation,dry,twitter,mvc,matsumoto,yellowpages,ruby on rails,tertiary gnment,hansson,model view controller]]>
      </tags>
      <license>by-nc</license>
      <thumbnail_url>http://i5.scribdassets.com/public/images/uploaded/4296197/5vge1lz48yaf2_thumbnail.jpg</thumbnail_url>
      <page_count>46</page_count>
    </result>
    ...
  </result_set>
</rsp>

3. Phantom User Accounts

Phantom user accounts help web applications with their own user authentication systems to integrate with Scribd's user model. For example, if you have a website that allows job seekers to add a resume, you could easily integrate your user model with ours, ensuring that each resume is attached to a phantom Scribd user who represents the job seeker who uploaded it. Having this type of user information will make searching and browsing user-scoped documents with the API much easier for you.

All you need to use this method is some unique identifier for each of your users like a username or ID. Pass this unique identifier as the value of the parameter my_user_id to any document method. The method will then be executed on behalf of a phantom Scribd user identified by the ue ID you gave us.

3.1. Uploading

First, upload a document. In this example we will use curl to POST a text file using multipart/form-data. Replace <api_key> with your API key and <my_user_id> with your system's user ID.

$ echo "This is a test." > test.txt
$ curl -F "file=@test.txt;type=text/plain" \
  "api.scribd.com/api?method=docs.upload&api_key=<api_key>&my_user_id=<my_user_id>"

3.2. Fetching

Upon completion of a successful upload, you can fetch a list of only the documents uploaded for that my_user_id:

$ curl "api.scribd.com/api?method=docs.getList&api_key=<api_key>&my_user_id=;my_user_id>"

If you would like to fetch all documents across all of your "phantom" accounts, include the use_api_account=true parameters:

$ curl "api.scribd.com/api?method=docs.getList&api_key=<api_key>&use_api_account=true"

3.3. Searching

If you would like to search within the context of a single "phantom" account, include my_user_id

$ curl "api.scribd.com/api?method=docs.search&api_key=<api_key>&query=ruby%20on%20rails&my_user_id=<my_user_id>"

If you would like to search across all of your "phantom" accounts, set scope=all:

$ curl "api.scribd.com/api?method=docs.search&api_key=<api_key>&query=ruby%20on%20rails&scope=all
scribd