Web Services

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
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.