Quickstart Guide
Introduction:
The OpenAmplify API is a web service you can access through a simple request to a URL.
At its simplest, the API reads text you supply and returns linguistic data explaining and classifying the content. What you do with that analysis is, in the fine tradition of APIs and mashups, up to you. Some possibilities might include pairing ads with articles, creating rich tag-clouds, or monitoring the tone of forum threads.
To use the API, you submit text via an HTTP POST or GET request (SOAP is allowed too, but not covered here) using whatever tools are appropriate to your coding language of choice. The API returns linguistic data about the text in any of a variety of formats (XML, JSON, etc) for you to parse and use in your code.
What does OpenAmplify do?
Like other text-analysis software, OpenAmplify identifies the parts of speech in submitted text. However, OpenAmplify goes considerably beyond that by capturing indicators of emotional meaning. For instance, OpenAmplify can identify the prominence of topics in the text, work out how the author feels about them, even see how committed an author is to actions they write about.
No software (yet) can send you back the Cliff's Notes of text you submit, but we think OpenAmplify is leading the race.
Registration and Credits:
Use of the API is free up to the first 1,000 “transactions” per day once you’ve registered for your free API key. Registering for an API key is as simple as signing up as a member of the community. Once you're logged in, go to your profile page to find your personal API key.
Submitting text for analysis counts as a single transaction.
If you anticipate needing more than 1,000 transactions per day, commercial arrangements are available. Contact us here.
Parameters
Regardless of coding language, you will submit parameters - including text or a url you want Amplified - to OpenAmplify's API URL.
API URL:
Parameters:
- apiKey=apiKey,
- inputText= text || sourceURL= url (e.g.: http://www.someURL.com)
- [analysis= all* || topics || actions || demographics || style} ]
- [outputFormat = xml* || json || dart ]
* = default
Definitions:
Without a key, your request won't be processed. To get a key, simply register on this site. Once you are logged in, find the link at the top right of the page that says "Edit". Clicking there takes you to the edit screen for your profile, where you will find your API key.
InputText is the text you want to submit to OpenAmplify. If you are using a GET request to submit your text, you should make sure to url encode it. Check the documentation for your coding language if necessary. POST requests require no pre-processing for the submitted text.
NOTE: You must include EITHER inputText OR sourceURL. If you submit a value for both, the url will be ignored.
If you specify an absolute url (e.g. "http://en.wikipedia.org/wiki/Semantic_web"), OpenAmplify will scrape the text from that page and analyze the content. However, be aware that the scraper may pick up ads, navigation and other visible text on the page that you don't really want analyzed.
Also, note that OpenAmplify's scraper is occasionally thrown by redirects. If you enter a sourceURL that the receiving server will redirect to another URL, you will probably receive an error. In light of this, try to make sure the URL you submit isn't redirected (for instance, if www.openAmplify.com redirects to www.openamplify.com, use the latter to avoid unnecessary errors).
If not specified, the default value of analysis is "all".
- all: Returns all of the following analyses
- topics: Returns data about the prominent topics in the text
- actions: Returns data about the prominent actions in the text
- demographics: Returns estimates of the author's demographic information
- style: Returns data about the style of the text - works best with longer selections
outputFormat = xml | empty
The default output format for the OpenAmplify service is xml. There are XML Schema documents for the results of the various analyses:
outputFormat = rdf
If you want to use OpenAmplify results in an RDF environment (such as Protoge - http://protege.stanford.edu/, tested with version 3.4) you can select the rdf output format. The RDF Schema is available at:
http://portaltnx.openamplify.com/AmplifyWeb_v21/rdf/AmplifyRDFFlatOutput.rdfs
outputFormat = rdfa
If you want to annotate your web pages with RDFa annotations (http://www.google.com/support/webmasters/bin/answer.py?answer=99170, http://developer.yahoo.net/blog/archives/2008/09/searchmonkey_support_for_rdfa_enabled.html), we output the people and organizations from the OpenAmplify analysis in RDFa format.
outputFormat = csv
If you do not want to parse xml, and will be using a SQL database or Spreadsheet to perform you analysis, we provide the results in Comma Separated Values format. Due to the limitations of the format, this will only return Topics from the Amplify analysis.
outputFormat = DART
If you are using DoubleClick's "DART for Publishers" as serving platform, you can get your OpenAmplify results as a JavaScript variable in DART format. Contact the Community Manager for further assistance integrating OpenAmplify into your DART environment.
outputFormat = oas
If you are using 24-7 Media's OAS ad serving platform, you can get your OpenAmplify results as a JavaScript variable in OAS format. Contact the Community Manager for further assistance integrating OpenAmplify into your 24-7 environment.
outputFormat = json
If you would like to use JavaScript to analyze the OpenAmplify results you can select json to get your results in JSON notation. http://www.json.org/
outputFormat - json_js
Very similar to the json format, except this is already assigned to a JavaScript variable, and can be used in client side scripting via the <SCRIPT SRC=...>
outputFormat - signals
If you want to analyze the results visually in your browser you should select the signals output format. This is a complete html page, with a graphically oriented presentation of the results.
outputFormat - pretty
This is a text oriented html presentation of the results.
Output: Processing the response
The API returns a linguistic analysis of the text you submitted. Data are returned in whichever of the available formats you set in outputformat. If you don't specify a format, the results are returned as XML.
Which data are returned depends on the value you set in the analysis parameter of your request. Setting analysis=all returns information about topics, actions, demographics and style. Using any of the other values returns just the corresponding subset of the full analysis.
A comprehensive overview of the XML's structure is available here.
Parameters
Cache = enable|disable (default enable)
OpenAmplify will cache the results of spidering a SourceURL for a period of time. The default value is "enable", and in most cases you will get the best performance when using the "enable" option. However, if you are having problems with your request or you are requesting content which changes very frequently you can use the "disable" option to force OpenAmplify to spider a new copy of that SourceURL.
OptimiseRespTime = enable|disable (default enable)
I like to call this the "Large Document Support" paramter. The default value is "enable", and in most cases you will get the best performance when using the "enable" option. However, if you are working with short texts (under 1K in length) using the "disable" option will result in somewhat better performance. Please note the British spelling of "OptimiSe"!!!!
MaxTopicResult = all|positive integer (default 10)
You would be surprised at the number of topics that OpenAmplify can identify in longer pieces of text. This parameter allows you to specify how many topic results you would like to receive. The text string "all" will return all of the identified topics in the text.
MaxActionResult = all|positive integer (default 10)
The same functionality as maxtopicresult, but applied to actions.
SortOrder = weight|document (default weight)
Inside of each container (such as Topics, Actions, etc.) OpenAmplify will sort a set of results based on the Value of that score. However, if you would like to receive the results sorted by the order in which they first appear in the input document, use the "document" option.=
Language specific tutorials
The following language-specific explanations focus on how to communicate with the API and parse results in the named coding language.
