Getting started with the API
The JRank API uses a very simple method of requesting search results. To query your context in JRank, use an HTTP GET on the following URL, making sure to replace [API key]
with your API key and [query]
with your query.
https://www.jrank.org/api/search/v2?key=[API key]&q=[query]
The parameters key
and q
are the only parameters that are required for JRank to return anything meaningful. You can also tell JRank to return certain pages of results, and change how many results are on each page. A list of the parameters are show below:
- key
- Your API key for the context you wish to search.
- You can search multiple contexts by repeating the key parameter like "&key[]=context1&key[]=context2", where context1 is the key to the first context you wish to include, context2 is the second, and so on.
- q
- The search query
- limit
- Limit the search results to this number (default: 10, max: 1000)
- start
- Start with this search result (default: 0)
Changing the output type
By default, JRank will return your results in HTML format. However, when programming with the API, it's usually much easier to manage data when represented in a more structured format, such as XML or JSON. To specify the format of the data JRank returns, specify the format as you would a regular filename. For example:
https://www.jrank.org/api/search/v2.xml?key=api_key_here&q=test+query
https://www.jrank.org/api/search/v2.json?key=api_key_here&q=test+query
What does the data mean?
The same type of data is returned by both the JSON, HTML, and XML formats. Below are the fields you have access to, as well as what each of them mean. At the most basic level are search results data. Each result has the fields url
, title
, and content
. In addition to the search results, there is additional data that describe the results, called metadata. Things like the available page numbers, next, previous, and current pages, or even the query words.
- prev_page
- Page number of the previous page
- prev_page_start
- Previous page's first result
- next_page
- Page number of the next page
- next_page_start
- Next page's first result
- current_page
- Page number of the current page
- start
- Current page's first result
- total_pages
- Total number of pages available
- total_found
- Total search results that were found
- total
- Total returned search results
- max
- Maximum number of results that will be shown
- limit
- Number of search results per page
- time
- Number of seconds taken to perform this search
- query
- Query string that was submitted
- words
- List of words that were parsed from the query string
- pages
- Pairs of page numbers and start indexes for each set of pages
- entries
- Each search result entry, with url, title, and description fields