API Definition

Getting Started

The NewsEdge OPENS API is a RESTFUL application programming interface to news services provided by Acquire Media's NewsEdge system. The OPENS API is language-independent and based on widely-supported Web standards. You access the API using standard uniform resource locators (URLs) in a REST-like methodology over the internet. The OPENS API uses the noun/verb pattern for API invocation, where the noun identifies a resource and the verb identifies an action to perform on the resource. For example, the news/search API acts on the news resource to perform a search. The returned results are in clearly defined XML.

The API supports the ability to create powerful search syntax without the need to include a library or a thick client. Besides obtaining returned results of highly relevant news or editorialized content in XML, the API also supports on-the-fly transformation of the XML results. Your application can easily convert the output into business-specific format such as HTML, XHTML, RSS, or any other format desired by processing with standard style sheets such as CSS (Cascading Style Sheets) or XSLT(Extensible Stylesheet Language Transformations).

Starting and Managing an API Session
All applications require the following minimum steps:
  1. Login to the session using session/login.
  2. Save the user-token and the uid elements from session/login to use as the session parameter and the user-ID value in other API requests.
  3. Manage the session with session/getactivesessions and re-login if the session times out.
  4. Logout of the session using session/logout.

The following example shows these steps. It also shows how to get information about each of the available APIs.

  1. Start a session.
    To start an API session, invoke session/login and include the name and password parameters.

    Request
    https://secure.newsedge.com/opensapi/20/session/login?name=<<user-name>>&password=<<user-password>>

    Response
    <?xml version="1.0" encoding="UTF-8"?>
<opens-api>
  <status>OK</status>
  <user-token>935DA0B364E9E130F0EC3827FC3CCC9C</user-token>
  <uid>32594</uid>
</opens-api>
  2. Save the user-token and uid.
    Save the returned value of the user-token element from session/login to use as the session parameter value for API requests that require a session ID. Also, save the uid element from session/login to use as the user-ID for other API requests, e.g. RSS feeds.
  3. List the APIs.

    To display all the available APIs, invoke api/list with the session parameter set to your user-token value.

    The results show every available API represented by an api element each with name and desc sub-elements. The list of available API is established for each user by the Acquire Media Administrator. (Some documented API may not be available for your use.)


    Request
    https://secure.newsedge.com/opensapi/20/api/list?session=935DA0B364E9E130F0EC3827FC3CCC9C

    Response
    <?xml version="1.0" encoding="UTF-8"?>
<opens-api>
  <status>OK</status>
  <api-list>
    <api>
      <name>alert/activate</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/adddestination</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/addschedule</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/addsearch</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/create</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/deactivate</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/delete</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/deletedestination</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/deleteschedule</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/deletesearch</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/info</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/list</name>
      <desc></desc>
    </api>
    <api>
      <name>alert/update</name>
      <desc></desc>
    </api>
    <api>
      <name>api/info</name>
      <desc></desc>
    </api>
    <api>
      <name>api/list</name>
      <desc></desc>
    </api>
    <api>
      <name>company/filings</name>
      <desc></desc>
    </api>
    <api>
      <name>company/quote</name>
      <desc></desc>
    </api>
    <api>
      <name>company/search</name>
      <desc></desc>
    </api>
    <api>
      <name>currency/convert</name>
      <desc></desc>
    </api>
    <api>
      <name>dictionary/search</name>
      <desc></desc>
    </api>
    <api>
      <name>geography/search</name>
      <desc></desc>
    </api>
    <api>
      <name>industry/search</name>
      <desc></desc>
    </api>
    <api>
      <name>internalnews/get</name>
      <desc></desc>
    </api>
    <api>
      <name>internalnews/getsources</name>
      <desc></desc>
    </api>
    <api>
      <name>internalnews/upload</name>
      <desc></desc>
    </api>
    <api>
      <name>news/read</name>
      <desc></desc>
    </api>
    <api>
      <name>news/search</name>
      <desc></desc>
    </api>
    <api>
      <name>pages/list</name>
      <desc></desc>
    </api>
    <api>
      <name>pdf/get</name>
      <desc></desc>
    </api>
    <api>
      <name>people/search</name>
      <desc></desc>
    </api>
    <api>
      <name>rss/get</name>
      <desc></desc>
    </api>
    <api>
      <name>rtf/get</name>
      <desc></desc>
    </api>
    <api>
      <name>savedsearch/create</name>
      <desc></desc>
    </api>
    <api>
      <name>savedsearch/delete</name>
      <desc></desc>
    </api>
    <api>
      <name>savedsearch/info</name>
      <desc></desc>
    </api>
    <api>
      <name>savedsearch/list</name>
      <desc></desc>
    </api>
    <api>
      <name>savedsearch/update</name>
      <desc></desc>
    </api>
    <api>
      <name>session/login</name>
      <desc></desc>
    </api>
    <api>
      <name>session/logout</name>
      <desc></desc>
    </api>
    <api>
      <name>source/search</name>
      <desc></desc>
    </api>
    <api>
      <name>storyfolder/addstory</name>
      <desc></desc>
    </api>
    <api>
      <name>storyfolder/create</name>
      <desc></desc>
    </api>
    <api>
      <name>storyfolder/delete</name>
      <desc></desc>
    </api>
    <api>
      <name>storyfolder/deletestory</name>
      <desc></desc>
    </api>
    <api>
      <name>storyfolder/info</name>
      <desc></desc>
    </api>
    <api>
      <name>storyfolder/list</name>
      <desc></desc>
    </api>
    <api>
      <name>storyfolder/update</name>
      <desc></desc>
    </api>
    <api>
      <name>storyfolder/updatestory</name>
      <desc></desc>
    </api>
    <api>
      <name>subject/search</name>
      <desc></desc>
    </api>
    <api>
      <name>taxonomy/search</name>
      <desc></desc>
    </api>
    <api>
      <name>topten/amexquotes</name>
      <desc></desc>
    </api>
    <api>
      <name>topten/nasdaqquotes</name>
      <desc></desc>
    </api>
    <api>
      <name>topten/nysequotes</name>
      <desc></desc>
    </api>
    <api>
      <name>weather/report</name>
      <desc></desc>
    </api>
  </api-list>
</opens-api>
  4. List API parameters.
    To get more information about a particular API, invoke api/info. This example gets information about the alert/activate API shown near the top of the previous results. The required parameters include:
    • noun set to alert
    • verb set to activate
    • session set to your user-token

    The results include details about the API's available input-parameters as well as user-settings for the current user.

    For example, you might have the following user settings for individual API:

    • concurrent - Controls the number of concurrent requests you can initiate for a particular API.
    • input - Provides user-specific default values for API parameters.
    • query - Controls your query parameter for a search API. It is a regular expression that replaces specific parts of a query and is typically used to restrict access. Its form is: <setting name="query">/input-match/output-replace/</setting>
    • rate - Controls the number of times per second that you can invoke a particular API. This value can be less than 1. For example, a value of 0.2 means you can call this API no more often than once every five seconds.

    Request
    https://secure.newsedge.com/opensapi/20/api/info?noun=alert&verb=activate&session=935DA0B364E9E130F0EC3827FC3CCC9C

    Response
    <?xml version="1.0" encoding="UTF-8"?>
<opens-api>
  <status>OK</status>
  <api-info>
    <noun>alert</noun>
    <verb>activate</verb>
    <desc></desc>
    <input-parameters>
      <parm>
        <name>session</name>
        <desc></desc>
        <default></default>
      </parm>
      <parm>
        <name>alert</name>
        <desc></desc>
        <default></default>
      </parm>
    </input-parameters>
    <user-settings>
      <setting name="rate">3</setting>
    </user-settings>
  </api-info>
</opens-api>
  5. Handle sessions.

    When an API executes successfully, most returned results contain a status element set to OK. If an error occurs, the status element is ERROR, as shown in this example.

    When the status value is ERROR, additional error element is included in the results. In this example, the error element message indicates the user-token is not valid, and it means your session is no longer active. An API session remains active as long as requests are made within 3 minutes, otherwise the session automatically closes.


    Request
    https://secure.newsedge.com/opensapi/20/api/info?noun=alert&verb=activate&session=935DA0B364E9E130F0EC3827FC3CCC9C

    Response
    <?xml version="1.0" encoding="UTF-8"?>
<opens-api>
  <status>ERROR</status>
  <error>Session [935DA0B364E9E130F0EC3827FC3CCC9C] is invalid for user [null]</error>
</opens-api>
  6. Manage sessions.

    Following the API response received above, use the sessions/getactivesessions to retrieve a list of available API session(s). If no active sessions are returned then re-invoke the session/login.

    To automatically handle the error, save the sessions/getactivesessions and the initial session/login URL in your application. When your application detects this error, do the following:

    1. request the session/getactivesessions for active user-tokens. If none are returned then go to the next step. Otherwise, skip the next step and go to step 3
    2. reinvoke the saved session/login URL
    3. resave value of the returned user-token element

    Request
    https://secure.newsedge.com/opensapi/20/session/getactivesessions?name=<<user-name>>&password=<<user-password>>

    Response
    <opens-api>
  <status>OK</status>
  <message>No active sessions for user API user</message>
</opens-api>
  7. Close the session.
    Every application should close the session when done by invoking session/logout with the session parameter set to your user-token value.

    Request
    https://secure.newsedge.com/opensapi/20/session/logout?session=935DA0B364E9E130F0EC3827FC3CCC9C

    Response
    <?xml version="1.0" encoding="UTF-8"?>
<opens-api>
  <status>OK</status>
  <message>User logged out using token 935DA0B364E9E130F0EC3827FC3CCC9C</message>
</opens-api>

session/login - Start an API session

Use session/login to start a session with the OPENS API server. It returns a user-token element that identifies the session. See also api/info where noun=api and verb=info.


Example

https://secure.newsedge.com/opensapi/20/session/login?name=<<user-name>>&password=<<user-password>>

Required Parameters

Parameter Values Description
nameA user name established by the Acquire Media Administrator.
passwordThe password associated with the user name.

Optional Parameters

Parameter Values Description
jsonDefault:0
0,1,2		The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format.
  • 0 - Return data in XML format.
  • 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used.
  • 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from session/login is an opens-api container element that includes status and user-token sub-elements,

opens-api

Name Values Description
statusOK, ERRORThe status of the request.
  • OK - Request completed successfully.
  • ERROR - An error occurred with the request. An error element contains a description of the error.
user-tokenA generated unique identifier of the session. Use this value as the session parameter in other API requests.
uidThe unique identifier linked to the user name. Use this value as the user-ID in other API requests.

session/getactivesessions - Return a list of active API sessions

Use session/getactivesessions to retrieve a list of available API sessions. This command should be used if the caller has lost the user-token that is currently in use.


Example

https://secure.newsedge.com/opensapi/20/session/getactivesessions?name=<<user-name>>&password=<<user-password>>

Required Parameters

Parameter Values Description
nameA user name established by the Acquire Media Administrator.
passwordThe password associated with the user name.

Optional Parameters

Parameter Values Description
jsonDefault:0
0,1,2		The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format.
  • 0 - Return data in XML format.
  • 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used.
  • 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from session/getactivessions is an opens-api container element that includes status and active-tokens sub-elements,

opens-api

Name Values Description
statusOK, ERRORThe status of the request.
  • OK - Request completed successfully. If there are active sessions, the return will contain the uid and active-tokens elements. If there are no active sessions, the return will contain a message element reflecting that case.
  • ERROR - An error occurred with the request. An error element contains a description of the error.
uidThe unique identifier linked to the user name. Use this value as the user-ID in other API requests.
active-tokensThe active-tokens element will contain either one or more user-token elements that can be used in other calls to the API

session/clearsessions - Disables all active API sessions

Use session/clearsessions to disable all active user-tokens. This api can be used in close down or error recovery code to clean up any active sessions when the user-token that is currently in use has been lost.


Example

https://secure.newsedge.com/opensapi/20/session/clearsessions?name=<<user-name>>&password=<<user-password>>

Required Parameters

Parameter Values Description
nameA user name established by the Acquire Media Administrator.
passwordThe password associated with the user name.

Optional Parameters

Parameter Values Description
jsonDefault:0
0,1,2		The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format.
  • 0 - Return data in XML format.
  • 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used.
  • 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from session/clearsessions is an opens-api container element that includes status and message sub-elements,

opens-api

Name Values Description
statusOK, ERRORThe status of the request.
  • OK - Request completed successfully. All active sessions have been disabled.
  • ERROR - An error occurred with the request. An error element contains a description of the error.
messageThe message element confirms the disabling of all sessions for the provided name.

session/logout - End an API session

Use session/logout to end a session with the OPENS API, which began with a session/login request. See also api/info with &noun=session&verb=logout.


Example

https://secure.newsedge.com/opensapi/20/session/logout?session=<<user-token>>

Required Parameters

Parameter Values Description
sessionThe ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter Values Description
jsonDefault:0
0,1,2		The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format.
  • 0 - Return data in XML format.
  • 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used.
  • 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The session/logout returns an opens-api container element that includes status and message sub-elements.

opens-api

Name Values Description
statusOK, ERRORThe status of the request.
  • OK - Request completed successfully.
  • ERROR - An error occurred with the request. An error element contains a description of the error.
messageIf the request is successful the text message indicates the user logged out and includes the user token. For example: 
<message>User logged out using token 935DA0B364E9E130F0EC3827FC3CCC9C</message>

If an error occurs, the error element is included instead of the message element.


api/list - List the APIs available to the current user

Use api/list to get the current user’s list of available APIs.


Example

https://secure.newsedge.com/opensapi/20/api/list?session=<<user-token>>

Required Parameters

Parameter Values Description
sessionThe ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter Values Description
jsonDefault:0
0,1,2		The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format.
  • 0 - Return data in XML format.
  • 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used.
  • 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The api/list returned results are an opens-api container element that includes status and api-list sub-elements.

opens-api

Name Values Description
statusOK, ERROR

The status of the request.

  • OK - Request completed successfully.
  • ERROR - An error occurred with the request. An error element contains a description of the error.
api-listA list of api sub-elements.
apiEach API is described in an api element, which includes the following sub-elements:
  • name
  • desc
    •
nameThe resource and name of the API in the format noun/verb. For example, session/login.
descA brief description of the API.

api/info - Get a description of an API for the current user

Use api/info to get a description of a specific API including a list of input parameters and current user settings. The request takes the parameters noun and verb, where noun is the API resource and verb is the action performed on the resource. For example, to get documentation about session/login, use &noun=session&verb=login. To get a complete list of the API, see api/list.


Example

https://secure.newsedge.com/opensapi/20/api/info?session=<<user-token>>&noun=<<api-resource>>&verb=<<api-name>>

Required Parameters

Parameter Values Description
nounA resource an API request acts upon. Valid values are in the name element from api/list.
verbThe API name and the action applied to the resource. Valid values depend on the value of the noun parameter. Valid values are in the name element from api/list.
sessionThe ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter Values Description
jsonDefault:0
0,1,2		The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format.
  • 0 - Return data in XML format.
  • 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used.
  • 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The api/info returned results are an opens-api container element that includes status and api-info sub-elements.

opens-api

Name Values Description
statusOK, ERROR

The status of the request.

  • OK - Request completed successfully.
  • ERROR - An error occurred with the request. An error element contains a description of the error.
api-infoContains a description of the API in the following sub-elements:
  • noun
  • verb
  • desc
  • input-parameters
  • user-settings
nounThe API resource name of the input request.
verbThe API action of the input request that is performed on the resource.
descA brief description of the API.
input-parametersContains a list of parm sub-elements representing the API’s parameters available to the current user. Note that some parameters documented for a particular API may not be available for your use.
parmEach parm element contains the following sub-elements:
  • name
  • desc
  • default
nameThe name of the parameter.
descA brief description of the parameter.
defaultThe parameter's default value, if any.
user-settingsContains an optional list of one or more user-specific setting sub-elements.
settings

Each setting element is identified by a name attribute. The setting values are specific to the currently logged in user and are set by the Acquire Media Administrator. Some possible settings include the following:

  • concurrent - An integer value that controls the number of concurrent requests you can invoke for a particular API request.
  • input - Provides user-specific default values for API parameters. The input user setting is a comma-separated list of parameter=value pairs, where a parameter is one of the API request's parameters. For example, searchDate=past30days means a date range of the past 30 days will be the default for all news/search requests. Note: to override the default value, submit the news/search request with the searchDate parameter set to your desired search date range.
  • query - Controls how your query behaves, such as restricting which sources your query can access. The query user setting is a regular expression that gets applied to the query parameter in a search. The format is: /input-match/output-replace/
  • rate - The number of times per second that your application can invoke a particular API request. For example, 5 means the API request can be invoked 5 times per second, while 0.2 means the API request can be invoked once every 5 seconds.