Web Services

Documentation » Fetch all Pages that include a Specific Term

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

The /recommend endpoint returns recommended content based on the given URL or topic. Reccommendations are given using the OpenEI search. If a URL is provided, this service will slurp content from that URL, feed the content to the REEGLE API to find terms, and feed those terms into OpenEI search for content recommendations.

Standard Request

The request URL provides the endpoint where your request will be sent. You'll need to send a GET request to:

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

You'll replace parameters with any of the request parameters. All requests must include a topic or URL.

Minimum Request Example

To retrieve search results for a topic:

GET https://openei.org/services/api/content_assist/recommend?topic=topic

Be sure to:

  • Replace topic with the topic you would like to search for.

To retrieve search results for a URL:

GET https://openei.org/services/api/content_assist/recommend?url=url

Be sure to:

  • Replace url with the URL you would like to search for.

Request Parameters

Parameter Required Value Description
topic url or topic is required
Type: string
Default: NULL

The topic is a topic or URL you would like to search for. The results will be the same as those returned using the OpenEI search user interface. If the topic and URL are both set and valid, the URL will be ignored. Topic requests are returned faster than URL requests, because URL requests get the data from the page and issue a call to the term extraction service (REEGLE API).
url url or topic is required
Type:Array of strings
Default: NULL

The url is a URL or topic you would like to search for. This content will be accessed as a public user. Privileged content is not accessible. Results are returned from the OpenEI wiki page.

For example, the topic "Gateway:Solar" would return terms and recommendations related to the page https://openei.org/wiki/Gateway:Solar.
callback No
Type: string
Default: NULL

The callback returns a 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
 Choose how many results to return for each entry type. For example, 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
 Choose which version of the API you would like to use. We reccomend using the latest version. 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

The value returned is an array of terms (terms.term, terms.definition) returned from the webpage that matched the OpenEI definitions namespace.
terms_raw
Type: array

The value returned is an array of raw terms from the webpage that matched the URL. term[0] is the term and term[1] is the relevance score returned from the REEGLE API.
pages
Type: array

The value returned is an array of recommended pages. Returns fields pages.name, pages.link (relative to https://openei.org/) and pages.type.

Examples

Get a list of recommendations in JSON format

Request

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

Be sure to:

  • Replace Gateway:Solar with the term or url you would like to search for.
  • Set the limit to the number of records you would like returned.

Response

 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. This is likely due to a failure of a downsteram service. The request cannot be processed at this time.

Additional Resources