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
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>"
<?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:
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.
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 "firstname.lastname@example.org;type=text/plain" \ "api.scribd.com/api?method=docs.upload&api_key=<api_key>&my_user_id=<my_user_id>"
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"
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