Page by SERPs.com CTO Joel Bradshaw
The SERPs Account API is a fully REST-compliant API, which means that the only URL you need to know to use it in your app is https://api.serps.com. Each result you get back will include links to the resources available to you from that point, and you (or your application) can follow the links provided to access the data you need. As a result, the response you get back may be more verbose than you are used to seeing in other RESTful HTTP-based APIs that don’t implement the full breadth of REST. This may be confusing initially, but once you realize how it is set up, it is easy to zero in on the data you need. If you’re impatient and want to just dive in, jump over to the Quickstart page in our docs, but the rest of this one-page guide should help orient you further.
The SERPs Account API makes it easy to take data from your SERPs.com account including rankings, link metrics and more to enhance your internal reporting dashboards or software.
At the top level, you currently have one resource available to you: your Organization. Within this resource are your Sites and Users. Sites contain Subpages, which contain Keywords, which contain Ranks. Again, each resultset includes URLs that will take you up and down the hierarchy. You can also, of course, access any given resource directly with the URL given.
One of the core principles of RESTful design is that the API should be self-documenting, which the SERPs API strives to be - each query you make gives you the information that you need, and also pointers to the other related data that is available. The API itself isn't the only documentation, however. There is an overview of the API, and what resources are available to you, at http://portal.serps.com/. There is also an API Console that lets you try explore the API and get an idea of what the results look like, right in the documentation. The documentation for each resource also includes links that will take you directly to the Console to explore that resource.
Current data available from the API includes:
In order to use the API, you need two things: an API token, which you request from us, and your SERPs login, which you already have. You supply the API key with an X-API-Token header in your request, and pass your SERPs login via HTTP Basic Authentication.
With these two pieces of data, you are able to access the API and all of the data under your account, via whatever client you would like that is capable of talking HTTPS. Currently there are SERPs-specific client libraries available for Java/Android and Ruby, but any REST-compatible library should be able to handle it just fine. At this time, the API is read-only, but that may change in the future.
As always, if you run into any problems, or have any questions, we’d be glad to help. You can contact us through our online form, call us at (503) 683-3470, or put in a request at our helpdesk by emailing firstname.lastname@example.org - in any case, we’ll help get you up and running.
The SERPs API is currently available on all custom plans.