AskSteem: Search API Docs

Hello Steemians,
Today I'd like to discuss the new AskSteem search API which allows developers to build search functionality into their applications.

The API currently has two endpoints search and suggestions.

Search

search - allows searching for posts on the AskSteem index by keyword, and supports all of the query types listed here.

Endpoint

The search API uses an HTTP endpoint located at https://api.asksteem.com/search.

NameDescriptionExample
qthe search querysearch+query
pgthe page of search results2

So a full query would look like:
https://api.asksteem.com/search?q=search+term
or
https://api.asksteem.com/search?q=search+term&pg=2

Using the Data

The AskSteem API returns a JSON response with search results, which should work with any programming language that has a JSON library.

{
    "pages": {
        "has_next": true,  // If there is another page of results
        "has_previous": false, // If there is a previous page
        "current": 1 // The current page of results
    },
    "hits": 171,  // The number of results found
    "results": [{  // a list of results
        "tags": ["steemit", "steem", "asksteem", "steem-project", "steemdev"], // tags of the result
        "title": "Introducing AskSteem - A steem search engine",  // the title of the result
        "author": "thekyle",  // author of search result
        "type": "post", // type: post or user
        "net_votes": 300, // the number of votes of the post
        "summary": "\nHello, Steemians!\nOver the past month, I've been building a new search engine that indexes the steem blockchain. It's currently live at asksteem.com. The goal of AskSteem is to provide a reliable, powerful, and fast search engine that is optimized for steem. In this post, I'd like to cover some of the features that are available. \nQuery Syntax\nThere are many different ways that you can query the AskSteem index. I've created a video demonstrating each of them, but you may also read their descrip",  // a short excerpt from the body of the post
        "permlink": "introducing-asksteem-a-steem-search-engine",  // the permlink
        "children": 89,  // number of comments
        "created": "2017-06-03T19:07:45"  // Creation date in ISO 8601 format (https://en.wikipedia.org/wiki/ISO_8601)
    }, {
        "tags": ["steemit", "asksteem", "steem", "steemdev", "mentions"],
        "title": "How to Find Posts that Mention You (with AskSteem)",
        "author": "thekyle",
        "type": "post",
        "net_votes": 228,
        "summary": "Hi, Steemians! \nA popular missing feature here on steemit is the ability to quickly and easily find posts that mention you using the @username syntax. This functionality comes baked right into AskSteem, a steem search engine. I wanted to write a quick blog post showing you how easy it is the utilize this powerful capability to interact with those who are talking about you in their posts.\n\n\n1. Go to AskSteem.com\n\nTo use this service you will need to visit AskSteem\n2. Type Your Username in Quotes\n",
        "permlink": "how-to-find-posts-that-mention-you-with-asksteem",
        "children": 59,
        "created": "2017-06-14T02:02:48"
    }, {
        "tags": ["steemit", "politics", "travel", "writing", "asksteem"],
        "net_votes": 83,
        "author": "asksteem",
        "type": "post",
        "title": "If a world war broke out, which country would you want to be in?  Answer Questions, EARN Steem!!!",
        "summary": "\n SteemIt Questions:\n1.] If a world war broke out, which country would you want to be in? and why ?\n2.] Would you join the fight in the name of your home country ?\n\nWe pay Steem for each answer! Also, well thought-out answers/popular votes gets 50 % of the post reward! \nGot a question you want to ask ?  just put in a bracket below [Question] and we\u2019ll use it in the next post. \n\nPrev Question: What is Driving the Price of SteemIt Downward ?\nPrev Question: How Does the Reward Curve Work  ?\n",
        "permlink": "if-a-world-war-broke-out-which-country-would-you-want-to-be-in-answer-questions-earn-steem",
        "children": 23,
        "created": "2017-03-06T23:24:24"
    }],
    "time": 0.404, // time it took for the query 
    "error": false // if an error occured
}

Suggestions

suggestions - provides suggested queries based on previous queries

Endpoint

The suggestions endpoint is https://api.asksteem.com/suggestions and takes only one parameter called term.
Like so:
https://api.asksteem.com/suggestions?term=asksteem

Using the Data

The suggestions API returns a list of at most 5 suggested queries and is out-of-the-box compatible with jQuery Autocomplete.

["asksteem", "asksteem logo", "asksteem funding", "asksteem sso", "asksteem login"]

Once again the data is also JSON and can be accessed from any language with a JSON processing library.

Rate-limit

There is currently no automatic mechanism for rate-limiting the API however, to ensure equal access for all developers please limit queries to 2-3 per second per IP address. If we find trouble makers we will permanently ban you, and if abuse becomes common we will begin requiring API authentication.

Required Attribution

Your use of this API is monetarily free, however, to support ourselves, we require that all applications using the API place AskSteem branding on the search results page in a location that is immediately visible to the user without any interaction on their part.

Branding Examples:

Here is an example of some HTML code to embed AskSteem branding:
<a href="https://www.asksteem.com"><img src="https://cdn.hoxly.com/asksteem/attribution.png" width="100px"></a>

Preview:

Final Thoughts

Now that every developer has the chance the harness the power of AskSteem I really cannot wait to see what you will do. If you make something cool with the API then please drop me a comment on this post, or message me on Steemit chat so I can check it out and maybe feature your application.

H2
H3
H4
3 columns
2 columns
1 column
2 Comments