NewsEdge API

Creating, Modifying and Using Web News Widgets.

Web News Widgets allow you to integrate NewsEdge stories and visualizations into your website with a minimum of coding.

Your first widget

In this example, we will be walking you through creating a simple headline widget and adding it to an example webpage.

Creating a widget based on a saved search
Placing the headlines on your page
Changing the widget to link to a story folder
Overriding the data source linked to your widget.

Creating a widget based on a saved search

Get the search ID.

Using the savedsearch/list api, save the ss value of the search you want to provide the headlines in your widget. In the example below, we want headlines about Pharmaceutical Development so we'll be using ss=13818

Request

https://secure.newsedge.com/opensapi/20/savedsearch/list?session=935DA0B364E9E130F0EC3827FC3CCC9C&level=PERSONAL

Response

  <opens-api>
    <status>OK</status>
    <savedsearches>
      <savedsearch ss="13819" owner="API User" level="PERSONAL" name="Drug Trials" permission="WRITE"/>
      <savedsearch ss="13821" owner="API User" level="PERSONAL" name="Patent and Market News" permission="WRITE"/>
      <savedsearch ss="13818" owner="API User" level="PERSONAL" name="Pharmaceutical Development" permission="WRITE"/>
      <savedsearch ss="13822" owner="API User" level="PERSONAL" name="Weekly Pfizer Report" permission="WRITE"/>
    </savedsearches>
  </opens-api>

Create a simple widget.
Using the defaults for most of the parameters, we will create a widget that uses the Pharmaceutical Development search. The call returns with a widget id of 110. We will use that identifier in all subsequent calls.

Request
```
https://secure.newsedge.com/opensapi/20/widget/create?session=935DA0B364E9E130F0EC3827FC3CCC9C&name=Widget&search=13818
```
Response
```
<opens-api>
<status>OK</status>
<widget>110</widget>
</opens-api>
```

Let's look at what you've created.

Using widget/info, you can see all the settings used by the widget/create call in the previous step.

Request

https://secure.newsedge.com/opensapi/20/widget/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&widget=110

Response

  <opens-api>
   <status>OK</status>
   <widget id="110" name="Widget" desc="NewsEdge Web News Widget" level="USER" permission="WRITE">
      <format>STANDARD</format>
      <resultsPerPage>5</resultsPerPage>
      <storydisplay>NEW</storydisplay>
      <storycontainerdiv/>
      <summary>FALSE</summary>
      <folderstatus/>
      <sourcetype>SEARCH</sourcetype>
      <source id="13818" name="Pharmaceutical Development"/>
      <type>IFRAME</type>
      <refresh>0</refresh>
      <layout/>
    </widget>
  </opens-api>

Placing the headlines on your page

The following steps enable the Web News Widget to be displayed on your page.

Make sure the DOCTYPE is declared.
It is important that the html DOCTYPE is declared at the top of your html code.
It should look like this:
```
<!DOCTYPE html> <html>... 
```
Include meta element to ensure the widget works with Internet Explorer clients.
Add this code within the head element in your html.
It should look like this:
```
<head> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />... 
```
Place the iframe on your page where you want the headlines to appear.
Add this code in the body of your html where the headlines are needed.
It should look like this:
```
<body> <iframe src="https://secure.newsedge.com/neif/110.html?refreshMinutes=0"/>... 
```

Changing the widget to link to a story folder

The data source for a widget can be a saved search or a story folder. In this example, we'll see how to identify the story folder and associate its ID to the widget.

Get the story folder ID.

Use the storyfolder/list API and identify which story folder contains the headlines to show in the widget. Save the story folder ID 17792 for the Industry News folder.

Request

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

Response

<opens-api>
  <status>OK</status>
  <storyfolders count="3">
    <storyfolder id="17792" order="3" count="6" sharing="" name="Industry News" description="" owner="API User" level="USER" permission="READ|WRITE|MANAGE" orderBy="RANK"/>
    <storyfolder id="17791" order="2" count="4" sharing="" name="My Stories" description="Stories for my homepage" owner="API User" level="USER" permission="READ|WRITE|MANAGE" orderBy="PUBDATE"/>
    <storyfolder id="17785" order="1" count="1" sharing="" name="My Stories manual fill TEST" description="" owner="API User" level="USER" permission="READ|WRITE|MANAGE" orderBy="DATEADDED"/>
  </storyfolders>
</opens-api>

Modifying the widget data source.
Using the widget/update API, specify the sourcetype will be FOLDER and with the optional parameter folder pass along the folder ID saved in the previous step.

By simply modifying the sourcetype of the widget, there is no need to change the html code on your page.

Request
```
https://secure.newsedge.com/opensapi/20/widget/update?session=935DA0B364E9E130F0EC3827FC3CCC9C&widget=110&sourcetype=FOLDER&folder=17792
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```

Overriding the data source linked to your widget.

As the widget is being requested, you can override the search or the story folder associated to the Web News Widget.

Determine the search you want to run.
For example, if you want stories about the mobile phone industry, you would use the ACME Industry code for [INDC:ii/tech.mobphone].
Pass the new query to the Web News Widget.
When calling the iframe in your html code, add a query parameter.
It should look like this:
```
<body> <iframe src="https://secure.newsedge.com/neif/110.html?refreshMinutes=0&query=([INDC:ii/tech.mobphone])"/>... 
```

widget/create - Create a new Web News Widgets

Use widget/create to create a new Web News Widget with the provided parameters. See also api/info where noun=widget and verb=create.

Example

https://secure.newsedge.com/opensapi/20/widget/create?session=<<user-token>>&name=<<widget-name>>&search=<<ss-id>>[&parameter=value][&. . .]
https://secure.newsedge.com/opensapi/20/widget/create?session=<<user-token>>&name=<<widget-name>>&folder=<<storyfolder-id>>[&parameter=value][&. . .]

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
name	url encoded string of length 50 or less.	An identifying name for this Web News Widget
data source		When a Web News Widget is created, the default source for the headlines must be specified. The headlines can come from a saved search (see the savedsearch/list api), or a story folder (see the storyfolder/list api). The source type is controlled providing either the search parameter or the folder parameter but not both.

Optional Parameters

Parameter	Values	Description
json	Default: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.
description	Default:NewsEdge Web News Widget url encoded string of length 200 or less.	A description of the Web News Widget.
type	Default:IFRAME IFRAME, PROXY	This parameter controls the integration style of the Web News Widget. If the parameter is set to IFRAME, use the following integration instructions: Before the <HTML> element, at the very top of the page add: <!DOCTYPE html> In the <HEAD> element, add: <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /> Paste the following <iframe> into the body where headlines are needed: <iframe src="https://secure.newsedge.com/neif/<<widget-id>>.html?refreshMinutes=0"></iframe> If this parameter is set to PROXY, use the following integration instructions: On your webserver, create a proxy pass and reverse proxy pass from /nenp/ and https://secure.newsedge.com/nenp/ Before the <HTML> element, at the very top of the page add: <!DOCTYPE html> In the <HEAD> element, add: <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /> <link rel="stylesheet" href="/nenp/<<widget-id>>.css" media="screen" /> <script type="text/javascript" src="/nenp/<<widget-id>>.js"></script> Note: if adding more than one Web News Widget to the same intranet page, include one CSS and one JS per Web News Widget. In the <BODY> element, add: <body onload="ne_win_init(0);"> Paste the following <DIV> into the body where headlines are needed: <div id="newspipe_<<widget-id>>"></div>
format	Default:STANDARD STANDARD, SKYSCRAPER, ZIPPER, HEATMAP, VENN, TAGCLOUD, SUNBURST, TRENDING	This parameter sets the contents of Web News Widget. Values include: STANDARD - Standard NewsEdge is a standard block of headlines and summaries. Typically used in main portion of your site. SKYSCRAPER - Skyscraper is a tall narrow list of headlines. Typically used in a side bar. ZIPPER - Zipper is a single horizontal line of headlines scrolling from right to left. This will run across the width of your site. HEATMAP - Heat Map + Standard NewsEdge is standard block of headlines and summaries, along with the Heat Map visualization diagram. VENN - Auto-Venn + Standard NewsEdge - standard block of headlines and summaries, along with the Auto-Venn visualization diagram. TAGCLOUD - Tag Cloud + Standard NewsEdge - standard block of headlines and summaries, along with the Tag Cloud visualization diagram. SUNBURST - Sunburst + Standard NewsEdge - standard block of headlines and summaries, along with the Sunburst diagram. TRENDING - Trending + Standard NewsEdge - standard block of headlines and summaries, along with the Trending Topics chart.
search	The ss parameter for the savedsearch returned from savedsearch/list or savedsearch/info	Either this parameter or folder but not both must be specified in a widget/create call. If this parameter is specified, then the saved search id will be the source of headlines for the Web News Widget.
folder	The folder parameter is set to the storyfolder id returned from storyfolder/list or storyfolder/info	Either this parameter or search but not both must be specified in a widget/create call. If this parameter is specified, then the provided story folder will be the source of the headlines for the Web News Widget.
folderstatus	Default:ACTIVE ALL, PENDING, ACTIVE, STORED	If the folder parameter is provided, this optional parameter controls which stories from the story folder are provided to the Web News Widget based on the story status.
level	Default:USER USER, GROUP, ACCOUNT	The level of authorization to change the Web News Widget. USER - Only the current API user can update or delete the Web News Widget. GROUP - Only users with group administrator role can update or delete the Web News Widget. ACCOUNT - Only users with account administrator role can update or delete the Web News Widget.
resultsPerPage	Default:5 1 - 100	This controls the number of headlines that will be displayed in the Web News Widget.
refresh	Default:0 0 - 30	If this parameter is non-zero, then the headlines will update every "refresh" minutes.
summary	Default:FALSE TRUE, FALSE	If summary is TRUE, then the story summary will be included in the display in the Web News Widget.
layout	Default:H1-50 H1-##, H2-##, V1-##, V2-##	If the type parameter is set to IFRAME and the format parameter is set to HEATMAP, VENN, TAGCLOUD, SUNBURST, or TRENDING, then this parameter controls the layout of the headlines and visualization. The headline part of the iframe will take up ## percent of the iframe width (if H1-## or H2-##) or height (if V1-## or V2-##). The default value is H1-50 which means that the headlines will be to the left of the iframe and the visualization will be to the right of the iframe with the headlines taking up 50% of the width of the iframe. Values include: H1-## - The headline display will be on the left side of the iframe and the visualization will be on the right side of the iframe. H2-## - The headline display will be on the right side of the iframe and the visualization will be on the left side of the iframe. V1-## - The headline display will be on top of the iframe and the visualization will be on the bottom of the iframe. V2-## - The headline display will be on bottom of the iframe and the visualization will be on the top of the iframe.
storydisplay	Default:NEW NEW, POP	If this parameter is set to NEW, a story read will open a new web page with the story display. If this parameter is set to POP and type is set to IFRAME, then a story read will replace the contents of the IFRAME with the story body. A link is shown to return to the headline display. If this parameter is set to POP and type is set to PROXY, then a story read will cause the story body to be inserted into a div with the name identified by the storycontainerdiv parameter.
storycontainerdiv		If the type parameter is set to PROXY, then this parameter is required to define the name of a <DIV> element on the html page where the story body is displayed when a story read is made.

Returned Results

Returned results are an opens-api element containing status and a widget id.

opens-api

Name

Values

Description

status

OK, ERROR

The status of the request.

OK - The request completed successfully.

ERROR - An error has occurred. Review api/info for parameter list.

widget

This is the numerical identifier of the widget that was created. It will be used as a parameter with widget/info, widget/update, widget/getstyles, widget/updatestyle, widget/resetstyles, and widget/delete APIs. It will also be returned by the widget/list API.

widget/list - List available Web News Widgets

Use widget/list to get a list of Web News Widgets. See also api/info where noun=widget and verb=list.

Example

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

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default: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 include an opens-api element with a widgets sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	If the status is OK, then a widgets element will be present that contains zero or more widget sub-elements. If the status is ERROR, then a message element will be present containing a text description of the error.
widgets		The widgets element contains zero of more widget sub-elements that describe the available Web News Widgets.

widgets

The widgets element contains zero or more widget sub-elements. Each widget sub-element has the attributes described below.

Name	Values	Description
id		The id is the unique identifier for this widget. It is a required parameter for all other widget API calls.
name		This is the name of the widget.
owner		Depending on the level attribute, this will be the name of the user, group or account that has administrative control of this widget.
level	USER,GROUP,ACCOUNT	If the level is USER, then the owner is the name of the user that created the widget and only that user can modify the widget. If the level is GROUP, then the owner is the name of the group of the user that created the widget. Only group administators for that group can modify the widget. If the level is ACCOUNT, then the owner is the name of the account of the user that created the widget. Only account administrators for that account can modify the widget.
permission	WRITE,READ	If the permission is WRITE, then the api user can modify this widget. If the permission is READ, then the api user only has read-access to the widget's settings.
desc		An optional text description of the widget.
createdBy		The name of the user that created the widget.
modifiedBy		The name of the user that last modified the widget.
modifiedOn		The date, in the form YYYYMMDDTHHMMSS-ZZZZ, when the widget was last modified.

widget/info - Get details on one Web News Widgets

Use widget/info to get details on a particular Web News Widgets. See also api/info where noun=widget and verb=info.

Example

https://secure.newsedge.com/opensapi/20/widget/info?session=<<user-token>>&widget=<<widget-id>>

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
widget		The ID of the Web News Widget. The widget comes from the widget/create or widget/list API returned results.

Optional Parameters

Parameter	Values	Description
json	Default: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

If the status is OK, the returned results include all the settings for the request widget.

opens-api

Name	Values	Description
status	OK, ERROR	If the status is OK, then a widget element that will contain the settings for the requested widget. If the status is ERROR, then a message element will be present containing a text description of the error.
widget		The widget element that will contain the settings for the requested widget.

widget

Name	Values	Description
id		The id is the unique identifier for this widget. It is a required parameter for all other widget API calls.
name		This is the name of the widget.
level	USER,GROUP,ACCOUNT	If the level is USER, then the owner is the name of the user that created the widget and only that user can modify the widget. If the level is GROUP, then the owner is the name of the group of the user that created the widget. Only group administrators for that group can modify the widget. If the level is ACCOUNT, then the owner is the name of the account of the user that created the widget. Only account administrators for that account can modify the widget.
permission	WRITE,READ	If the permission is WRITE, then the api user can modify this widget. If the permission is READ, then the api user only has read-access to the widget's settings.
desc		Text description of the widget. When using widget/create, the default text "NewsEdge Web News Widget" is given to this element.
format	STANDARD, SKYSCRAPER, ZIPPER, HEATMAP, VENN, TAGCLOUD, SUNBURST, TRENDING	This describes the format of the widget as one of the following: STANDARD - Standard NewsEdge is a standard block of headlines and summaries. Typically used in main portion of your site. SKYSCRAPER - Skyscraper is a tall narrow list of headlines. Typically used in a side bar. ZIPPER - Zipper is a single horizontal line of headlines scrolling from right to left. This will run across the width of your site. HEATMAP - Heat Map + Standard NewsEdge is standard block of headlines and summaries, along with the Heat Map visualization diagram. VENN - Auto-Venn + Standard NewsEdge - standard block of headlines and summaries, along with the Auto-Venn visualization diagram. TAGCLOUD - Tag Cloud + Standard NewsEdge - standard block of headlines and summaries, along with the Tag Cloud visualization diagram. SUNBURST - Sunburst + Standard NewsEdge - standard block of headlines and summaries, along with the Sunburst diagram. TRENDING - Trending + Standard NewsEdge - standard block of headlines and summaries, along with the Trending Topics chart.
resultsPerPage	1-100	This describes the number of headlines shown in the widget.
storydisplay	NEW, POP	This describes how the story is to be displayed. If set to NEW, a story read will open a new web page with the story display. If set to POP and type is set to IFRAME, then a story read will replace the contents of the IFRAME with the story body. A link is shown to return to the headline display. If set to POP and type is set to PROXY, then a story read will cause the story body to be inserted into a div with the name identified by the storycontainerdiv parameter.
storycontainerdiv		When the type parameter is set to PROXY, then this defines the name of a <DIV> element on the html page where the story body is displayed when a story read is made.
summary	TRUE, FALSE	If this is TRUE, then the story summary is displayed along with the headline.
folder	ALL, PENDING, ACTIVE, STORED	If sourcetype is set to FOLDER, this controls which stories from the story folder are provided to the Web News Widget based on the story status. ALL - shows all stories in the story folder. PENDING - shows only the story folder stories with status as Pending. ACTIVE - shows only the story folder stories with status as Active. STORED - shows only the story folder stories with status as Stored.
sourcetype	SEARCH, FOLDER	This describes the source of results displayed in the Web News Widget. SEARCH - the source of content for the Web News Widget is a saved search. FOLDER - the source of content for the Web News Widget is a story folder.
source		This describes the saved search or story folder associated to the Web News Widget. The source element contains the following attributes: id - the saved search ss id or the story folder id. name - the saved search or story folder name.
type	IFRAME, PROXY	This describes the deployment type of the Web News Widget. If the type is IFRAME, use the following integration instructions: Before the <HTML> element, at the very top of the page add: <!DOCTYPE html> In the <HEAD> element, add: <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /> Paste the following <iframe> into the body where headlines are needed: <iframe src="https://secure.newsedge.com/neif/<<widget-id>>.html?refreshMinutes=0"></iframe> If type is PROXY, use the following integration instructions: On your webserver, create a proxy pass and reverse proxy pass from /nenp/ and https://secure.newsedge.com/nenp/ Before the <HTML> element, at the very top of the page add: <!DOCTYPE html> In the <HEAD> element, add: <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /> <link rel="stylesheet" href="/nenp/<<widget-id>>.css" media="screen" /> <script type="text/javascript" src="/nenp/<<widget-id>>.js"></script> Note: if adding more than one Web News Widget to the same intranet page, include one CSS and one JS per Web News Widget. In the <BODY> element, add: <body onload="ne_win_init(0);"> Paste the following <DIV> into the body where headlines are needed: <div id="newspipe_<<widget-id>>"></div>
refresh	0-30	This describes how frequently the Web News Widget results are to be refreshed.
layout	H1-##, H2-##, V1-##, V2-##	If the widget type is IFRAME and the format parameter is set to HEATMAP, VENN, TAGCLOUD, SUNBURST, or TRENDING, then this describes the layout of the headlines and visualization. The headline part of the iframe will take up ## percent of the iframe width (if H1-## or H2-##) or height (if V1-## or V2-##). Values include: H1-## - The headline display will be on the left side of the iframe and the visualization will be on the right side of the iframe. H2-## - The headline display will be on the right side of the iframe and the visualization will be on the left side of the iframe. V1-## - The headline display will be on top of the iframe and the visualization will be on the bottom of the iframe. V2-## - The headline display will be on bottom of the iframe and the visualization will be on the top of the iframe.

widget/update - Change settings for an existing Web News Widget

Use widget/update to change the operational settions for an existing Web News Widget. Only the parameters that are being updated need to be included in the call. See also api/info where noun=widget and verb=update.

Example

https://secure.newsedge.com/opensapi/20/widget/update?session=<<user-token>>&widget=<<widget>>[&parameter=value][&. . .]

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
widget	This is the id returned from widget/create or widget/list.	The numeric id for this Web News Widget.

Optional Parameters

Parameter	Values	Description
json	Default: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.
name	url encoded string of length 50 or less.	An identifying name for this Web News Widget
description	Default:NewsEdge Web News Widget url encoded string of length 200 or less.	A description of the Web News Widget.
type	Default:IFRAME IFRAME, PROXY	This parameter controls the integration style of the Web News Widget. If the parameter is set to IFRAME, use the following integration instructions: Before the <HTML> element, at the very top of the page add: <!DOCTYPE html> In the <HEAD> element, add: <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /> Paste the following <iframe> into the body where headlines are needed: <iframe src="https://secure.newsedge.com/neif/<<widget-id>>.html?refreshMinutes=0"></iframe> If this parameter is set to PROXY, use the following integration instructions: On your webserver, create a proxy pass and reverse proxy pass from /nenp/ and https://secure.newsedge.com/nenp/ Before the <HTML> element, at the very top of the page add: <!DOCTYPE html> In the <HEAD> element, add: <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /> <link rel="stylesheet" href="/nenp/<<widget-id>>.css" media="screen" /> <script type="text/javascript" src="/nenp/<<widget-id>>.js"></script> Note: if adding more than one Web News Widget to the same intranet page, include one CSS and one JS per Web News Widget. In the <BODY> element, add: <body onload="ne_win_init(0);"> Paste the following <DIV> into the body where headlines are needed: <div id="newspipe_<<widget-id>>"></div>
format	Default:STANDARD STANDARD, SKYSCRAPER, ZIPPER, HEATMAP, VENN, TAGCLOUD, SUNBURST, TRENDING	This parameter sets the contents of Web News Widget. Values include: STANDARD - Standard NewsEdge is a standard block of headlines and summaries. Typically used in main portion of your site. SKYSCRAPER - Skyscraper is a tall narrow list of headlines. Typically used in a side bar. ZIPPER - Zipper is a single horizontal line of headlines scrolling from right to left. This will run across the width of your site. HEATMAP - Heat Map + Standard NewsEdge is standard block of headlines and summaries, along with the Heat Map visualization diagram. VENN - Auto-Venn + Standard NewsEdge - standard block of headlines and summaries, along with the Auto-Venn visualization diagram. TAGCLOUD - Tag Cloud + Standard NewsEdge - standard block of headlines and summaries, along with the Tag Cloud visualization diagram. SUNBURST - Sunburst + Standard NewsEdge - standard block of headlines and summaries, along with the Sunburst diagram. TRENDING - Trending + Standard NewsEdge - standard block of headlines and summaries, along with the Trending Topics chart.
sourcetype	SEARCH, FOLDER	This is the data source for the headlines in this Web News Widget. If this parameter is equal to SEARCH, then the search parameter is required. If this parameter is equal to FOLDER, then the folder parameter is required.
search	The ss parameter for the savedsearch returned from savedsearch/list or savedsearch/info	If sourcetype is unspecified or is set to SEARCH, then this parameter is required. It is the saved search id for the search that will provide the headlines for the Web News Widget.
folder	The folder parameter is the storyfolder id returned from storyfolder/list or storyfolder/info	If sourcetype is set to FOLDER, then this parameter is required. It is the id for the story folder that will provide the headlines for the Web News Widget.
folderstatus	Default:ACTIVE ALL, PENDING, ACTIVE, STORED	If sourcetype is set to FOLDER, this optional parameter controls which stories from the story folder are provided to the Web News Widget based on the story's status.
level	Default:USER USER, GROUP, ACCOUNT	The level of authorization to change the Web News Widget. USER - Only the current API user can update or delete the Web News Widget. GROUP - Only users with group administrator role can update or delete the Web News Widget. ACCOUNT - Only users with account administrator role can update or delete the Web News Widget.
resultsPerPage	Default:5 1 - 100	This controls the number of headlines that will be displayed in the Web News Widget.
refresh	Default:0 0 - 30	If this parameter is non-zero, then the headlines will update every "refresh" minutes.
summary	Default:FALSE TRUE, FALSE	If summary is TRUE, then the story summary will be included in the display in the Web News Widget.
layout	Default:H1-50 H1-##, H2-##, V1-##, V2-##	If the type parameter is set to IFRAME and the format parameter is set to HEATMAP, VENN, TAGCLOUD, SUNBURST, or TRENDING, then this parameter controls the layout of the headlines and visualization. The headline part of the iframe will take up ## percent of the iframe width (if H1-## or H2-##) or height (if V1-## or V2-##). The default value is H1-50 which means that the headlines will be to the left of the iframe and the visualization will be to the right of the iframe with the headlines taking up 50% of the width of the iframe. Values include: H1-## - The headline display will be on the left side of the iframe and the visualization will be on the right side of the iframe. H2-## - The headline display will be on the right side of the iframe and the visualization will be on the left side of the iframe. V1-## - The headline display will be on top of the iframe and the visualization will be on the bottom of the iframe. V2-## - The headline display will be on bottom of the iframe and the visualization will be on the top of the iframe.
storydisplay	Default:NEW NEW, POP	If this parameter is set to NEW, a story read will open a new web page with the story display. If this parameter is set to POP and type is set to IFRAME, then a story read will replace the contents of the IFRAME with the story body. A link is shown to go back to the headline display. If this parameter is set to POP and type is set to PROXY, then a story read will cause the story body to be inserted into a div with the name identified by the storycontainerdiv parameter.
storycontainerdiv		If the type parameter is set to PROXY, then this parameter is required to define the name of a <DIV> element on the html page where the story body is displayed when a story read is made.

Returned Results

Returned results are an opens-api element containing status.

opens-api

Name

Values

Description

status

OK, ERROR

The status of the request.

OK - The request completed successfully.

ERROR - An error has occurred. Review api/info for parameter list.

widget/getstyles - Retrieve css styles for headlines or story display

Use widget/getstyles to retrieve the currently configured css styles for the display of the headlines or story body. See also api/info where noun=widget and verb=getstyles.

Example

https://secure.newsedge.com/opensapi/20/widget/getstyles?session=<<user-token>>&widget=<<widget>>
https://secure.newsedge.com/opensapi/20/widget/getstyles?session=<<user-token>>&widget=<<widget>>&region=STORY

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
widget	This is the id returned from widget/create or widget/list.	The numeric id for this Web News Widget.

Optional Parameters

Parameter	Values	Description
json	Default: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.
region	Default:HEADLINES HEADLINES, STORY	If region is set to HEADLINES, this call will return the css styles for the headline display within the Web News Widget. If region is set to STORY, this call will return the css styles for the story display within the Web News Widget.

Returned Results

Returned results are an opens-api element containing status, a widget id and a region child element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - The request completed successfully. ERROR - An error has occurred. Review api/info for parameter list.
widget		This is the numerical identifier of the widget for which the styles were requested.
region		The region element contains a name child element and one or more field child elements.
name		The name element value represents the format of the widget. If the requested region is HEADLINE, then the name value is STANDARD, ZIPPER, or SKYSCRAPER. When the widget format is HEATMAP, VENN, TAGCLOUD, SUNBURST or TRENDING, and the requested region is HEADLINE, the name value is STANDARD. If the requested region is STORY, the name value is STORY.

field

Name	Values	Description
label		The label is a short, human-readable title for this style. It is also the field parameter value passed to widget/updatestyle to change the style string.
name		The name parameter, when appended with "_widget", is the class name within the Web News Widget. For example, if the name parameter is newspipeResultItemStoryLink and the widget identifier is 99, then all of the hrefs surrounding the headline string will have a class of newspipeResultItemStoryLink_99.
description		This is a human-readable description of this style.
style		These are the css styles that will be assigned to this class in the Web News Widget. Any listed style can be changed by calling widget/updatestyle
default	TRUE, FALSE	If default is TRUE, the style string is the system-provided default. If default is FALSE, the style has been edited away from the system-provided default. widget/resetstyles can be called to return the style string back to the system-provided default.

widget/updatestyle - Change css style for a headline or story display style.

Use widget/updatestyle to modify the configured css styles for the display of the headlines or story body. See also api/info where noun=widget and verb=updatestyle.

Example

https://secure.newsedge.com/opensapi/20/widget/updatestyle?session=<<user-token>>&widget=<<widget id>>&field=<<field name>>&style=<<style string>>
https://secure.newsedge.com/opensapi/20/widget/updatestyle?session=<<user-token>>&widget=<<widget id>>&field=<<field name>>&style=<<style string>>[&parameter=value][&. . .]

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
widget	This is the id returned from widget/create or widget/list.	The numeric id for this Web News Widget.
field		This is the label of the field returned from widget/getstyles.
style		These are the styles that will be updated for the indicated field. The styles that can be changed are: color, font-family, font-size, font-weight, font-style, text-decoration, and background-color.

Optional Parameters

Parameter	Values	Description
json	Default: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.
region	Default:HEADLINES HEADLINES, STORY	If region is set to HEADLINES, this call will update the css style for the indicated field headline display within the Web News Widget. If region is set to STORY, this call will update the css style for the indicated field for the story display within the Web News Widget.

Returned Results

Returned results are an opens-api element containing status.

opens-api

Name

Values

Description

status

OK, ERROR

The status of the request.

OK - The request completed successfully.

ERROR - An error has occurred. Review api/info for parameter list.

widget/resetstyles - Return the styles for a field back to system-provided defaults.

Calling widget/resetstyles will return all the styles for the indicated region back to system defaults. See also api/info where noun=widget and verb=resetstyles.

Example

https://secure.newsedge.com/opensapi/20/widget/resetstyles?session=<<user-token>>&widget=<<widget id>>&region=<<HEADLINES|STORY>>

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
widget	This is the id returned from widget/create or widget/list.	The numeric id for this Web News Widget.
region	HEADLINES, STORY	This is the region for which all styles will be returned to their defaults.

Optional Parameters

Parameter	Values	Description
json	Default: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

A successful call will reset all the styles for the indicated region to the system-provided defaults and will return the new styles, in the same format as the return from widget/getstyles.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - The request completed successfully. ERROR - An error has occurred. Review api/info for parameter list.
widget		This is the numerical identifier of the widget for which the styles were requested.
region		The region element contains a name child element and one or more field child elements.
name		The name element value represents the format of the widget. If the requested region is HEADLINE, then the name value is STANDARD, ZIPPER, or SKYSCRAPER. When the widget format is HEATMAP, VENN, TAGCLOUD, SUNBURST or TRENDING, and the requested region is HEADLINE, the name value is STANDARD. If the requested region is STORY, the name value is STORY.

field

Name	Values	Description
label		The label is a short, human-readable title for this style. It is also the field parameter value passed to widget/updatestyle to change the style string.
name		The name parameter, when appended with "_widget", is the class name within the Web News Widget. For example, if the name parameter is newspipeResultItemStoryLink and the widget identifier is 99, then all of the hrefs surrounding the headline string will have a class of newspipeResultItemStoryLink_99.
description		This is a human-readable description of this style.
style		These are the css styles that will be assigned to this class in the Web News Widget. Any listed style can be changed by calling widget/updatestyle
default	TRUE, FALSE	If default is TRUE, the style string is the system-provided default. If default is FALSE, the style has been edited away from the system-provided default. widget/resetstyles can be called to return the style string back to the system-provided default.

widget/delete - Completely remove a Web News Widget from the system.

This call will completely remove the indicated Web News Widget from the system.

There is no recovery from this call.

See also api/info where noun=widget and verb=delete.

Example

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

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
widget	This is the id returned from widget/create or widget/list.	The numeric id for this Web News Widget.

Optional Parameters

Parameter	Values	Description
json	Default: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

Returned results are an opens-api element containing status.

opens-api

Name

Values

Description

status

OK, ERROR

The status of the request.

OK - The request completed successfully.

ERROR - An error has occurred. Review api/info for parameter list.

API Definition

Creating, Modifying and Using Web News Widgets.

widget/create - Create a new Web News Widgets

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

widget/list - List available Web News Widgets

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

widgets

widget/info - Get details on one Web News Widgets

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

widget

widget/update - Change settings for an existing Web News Widget

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

widget/getstyles - Retrieve css styles for headlines or story display

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

field

widget/updatestyle - Change css style for a headline or story display style.

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

widget/resetstyles - Return the styles for a field back to system-provided defaults.

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

field

widget/delete - Completely remove a Web News Widget from the system.

Example

Required Parameters

Optional Parameters

Returned Results

opens-api