Documentation » GET /services/api/content_assist/recommend

GET /services/api/content_assist/recommend

Provides recommended content based on the given URL or topic. If a topic (e.g. "Solar") is provided, gives recommendations based on content found at https://openei.org/search/. Optionally, if a URL is provided, this service will slurp content from that URL, feed the content to the REEGLE API to find terms, then feed those terms into https://openei.org/search/ for content recommendations.

Request URL
Request Parameters
Response Fields
Examples
- JSON Output Format
Errors

Request URL

GET https://apps.openei.org/services/api/content_assist/recommend?parameters

Request Parameters

Parameter	Required	Value	Description
topic	url or topic is required	Type: string Default: NULL	The topic to feed to the recommendation engine. This is the search term to be fed into https://openei.org/search/. If topic and URL are both set and valid, URL will be ignored. Topic requests will be faster than URL requests, since URL gets the data from the page and issues a call to the term extraction service (REEGLE API).
url	url or topic is required	Type:Array of strings Default: NULL	The URL of the page to get terms and recommendations for. This content will be accessed as a public user, privileged content is not accessible. This is relative to https://openei.org/wiki/. Example: "Gateway:Solar" would return terms and recommendations related to the page https://openei.org/wiki/Gateway:Solar.
callback	No	Type: string Default: NULL	The plaintext jsonp callback to wrap around the JSON object. If included e.g. ?callback=jsonp12345, the response will look like this: jsonp12345( { ... } )
limit	No	Type: Integer Default: 3	Limit the number of results in each group. For instance, if a limit of 2 is set, the response will return no more than 2 entries per type (Articles, Definitions, Images etc).
version	No	Type: Integer Default:1	Return a specific version of this API. When OpenEI releases a new version, backwards compatibility of new data to older API versions is a goal, though it is not guaranteed.

Response Fields

Field	Value	Description
terms	Type: array	Array of terms (terms.term, terms.definition) on the page that matched the OpenEI definitions namespace.
terms_raw	Type: array	Array of raw terms from the URL page content. term[0] is the term and term[1] is the relevance score returned from the REEGLE API.
pages	Type: array	Array of recommended pages. Returns fields pages.name, pages.link (relative to https://openei.org/) and pages.type.

Examples

JSON Output Format

GET /services/api/content_assist/recommend?url=Gateway:Solar&callback=callback&limit=2

    
      
        
      callback({
    "terms": [
        {
            "term": "Energy",
            "definition": "Broadly defined as the capacity to do work. There are many forms of energy..."
        },
        {
            "term": "Solar energy",
            "definition": "Radiant energy emitted by the sun"
        }
    ],
    "terms_raw": [
        [
            "solar",
            100
        ],
        [
            "energy",
            61
        ]
    ],
    "pages": [
        {
            "name": "ECOWAS Clean Energy Gateway",
            "link": "/wiki/Gateway:ECOWAS_Clean_Energy_Gateway",
            "type": "Articles"
        },
        {
            "name": "Approve Page",
            "link": "/wiki/Help:Approve_Page",
            "type": "Help Pages"
        },
        {
            "name": "Enhanced Geothermal Systems",
            "link": "/wiki/Definition:Enhanced_Geothermal_Systems",
            "type": "Definitions"
        },
        {
            "name": "Wilson Eric Bio Photo2.jpg",
            "link": "/wiki/File:Wilson_Eric_Bio_Photo2.jpg",
            "type": "Images"
        },
        {
            "name": "0383(2011).pdf",
            "link": "/wiki/File:0383(2011).pdf",
            "type": "Documents"
        },
        {
            "name": "Ryan's response",
            "link": "community/node/12#comment-2",
            "type": "Community"
        },
        {
            "name": "NREL-nv-80m.jpg",
            "link": "/wiki/File:NREL-nv-80m.jpg",
            "type": "Map Files"
        },
        {
            "name": "STIL2 Swedish Office Buildings Survey",
            "link": "/datasets/node/37",
            "type": "Datasets"
        }
    ]
})
      

  

Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned:

HTTP Status Code	Description
400	Invalid Request - One or more parameters did not pass validation, or a parameter may be missing. Check the error section of the response to see how the request url should be modified to address the error.
500	A problem occurred on the server-side, likely due to a failure of a downsteram service. The request cannot be processed at this time.

Web Services