Each API endpoint has different parameters that can be sent along in the request or properties returned in the response. However, a few elements of them are common to almost every endpoint in the API. Let's take a look at each one in a bit more detail.

Request Parameters

Limit Parameter

Often times when you make an API call, there may be hundreds or thousands, or even tens of thousands of results. To ensure efficient performance of the API, we set a default limit of 50 results returned per call. Using the parameter limit you can change this to your preferred value.

The maximum value you can use is 100. Making a request with a limit greater than 100 will receive a error. If this parameter is omitted, a default of 50 will be used.

Start Parameter

If all calls are limited to a 100 results, how do you get all results if there are more than this? That's where the parameter start comes in. This parameter represents the index of the first result in the set returned. The default for start is 0, which is the first item in the collection.

For example, let's say you want to make a request to a collection that contains 1,000 results. If your first request is set to limit=50 and start=0, you will get back items 0-49. If you want the next page of results, you will set limit=50 and start=50 to get items 50-99. After this, you'd use limit=50 and start=100, and so on.

Fields Parameter

When you make a request for a resource, by default we return all fields we have available for each result. Often times however, you may only require a small subset of this data. By using the fields parameter to only request the data you need, you may simply the response and speed up the response time.

The fields parameter should contain each field you'd like to request, separated by a comma. If this parameter is omitted, all fields will be returned.

fields=keyword,site,search_volume,ranking

For example, one item in response for the Keyword Rankings endpoint will look like following by default:

{
  "keyword": "4 star hotels",
  "begin_date": "10-10-2015",
  "end_date": "11-10-2015",
  "site": {
    "name": "example.com",
    "id": 2776
  },
  "search_engine": google|us|en-US|desktop,
  "keyword_groups": [
    {
      "name": "Hotels",
      "id": 864
    }
  ],
  "search_volume": 495001,
  "preferred_landing_page": "example.com/Hotels",
  "translation": "",
  "tags": [
    {
      "name": " Hotels",
      "id": 632
    },
    {
      "name": "  Luxury",
      "id": 674
    }
  ],
  "region": "United States",
  "ranking": [
    {
      "url": "https://www.example.com/url-one",
      "position_begin_date": 4,
      "position_end_date": 1,
      "position_change": 3
    },
    {
      "url": "https://www.example.com/url-two",
      "position_begin_date": 8,
      "position_end_date": 10,
      "position_change": -2
    }
  ]
},

If you only care about the keyword and ranking, you can set the fields parameter to fields=keyword,ranking to get the following response:

{
  "keyword": "4 star hotels",
  "ranking": [
    {
      "url": "https://www.example.com/url-one",
      "position_begin_date": 4,
      "position_end_date": 1,
      "position_change": 3
    },
    {
      "url": "https://www.example.com/url-two",
      "position_begin_date": 8,
      "position_end_date": 10,
      "position_change": -2
    }
  ]
},

By contrast, this is much simpler to work with and may be faster than the previous request.

Please note that only top-level fields are valid. If a field is the property of another object (such as position_begin_date, which is a property of the ranking object) it is not a valid value. Please use the top-level object instead (such as the ranking object).

Authorization Request Header

All API calls must be authenticated using Basic HTTP Authentication. As the name implies, this protocol is quite simple.

All requests must include the following HTTP request header:

Authorization: Basic {CREDENTIALS}

Where {CREDENTIALS} is a Base64 encoding of the string {username}:{password}.

(Please remember that this is your API username and password, which will be different than the one you use to log into the user interface. If you do not have API credentials, please email support@dragonmetrics.com.)

For example:

Username: johdoe
Password: Lh78B30#grCgo%
Before Base64: johndoe:Lh78B30#grCgo%
After Base64: am9obmRvZTpMaDc4QjMwI2dyQ2dvJQ==
Full HTTP Request Header: Authorization: Basic am9obmRvZTpMaDc4QjMwI2dyQ2dvJQ==

Now you can make calls to the API, including this header in every request. If there is an issue with your authorization you'll receive a 401 (Unauthorized) error message.

IMPORTANT REMINDER: Although your username and password are encoded using Basic Authentication, they are not encrypted. Therefore, it's important to always send requests over HTTPS. All requests made over HTTP will be sending your username and password in plain text, and will result in a 403 (Forbidden) error response.

Response Objects

Results Object

When an API is successful, almost all endpoints deliver the payload of the results in the results object. This object is used only to separate the results of the request from its meta data such as paging or error messages, so the contents of this object will vary by the endpoint.

For example:

{
  "results": [
    {
      ...
    },
    {
      ...
    }
    ...
  ],
  "paging": {
    "total": 846,
    "limit": 50,
    "start": 0,
    "prev": "https://api.dragonmetrics.com/v1.0/campaigns?limit=50&start=0",
    "self": "https://api.dragonmetrics.com/v1.0/campaigns?limit=50&start=50",
    "next": "https://api.dragonmetrics.com/v1.0/campaigns?limit=50&start=100"
  }
}

Paging Object

Using limit and start to page through large sets of results is simple enough, but we actually try to make it easier for you. Just about every API reponse contains a paging object, that contains everything you need to know about navigating around the entire set of results.

Here's an example of a typical response:

"paging": {
    "total": 648,
    "limit": 50,
    "start": 50,
    "prev": https://api.dragonmetrics.com/v1.0/campaigns?limit=50&start=0,
    "self": "https://api.dragonmetrics.com/v1.0/campaigns?limit=50&start=50",
    "next": https://api.dragonmetrics.com/v1.0/campaigns?limit=50&start=100

Let's take a look at this in a bit more detail:

  • The first property, total, is the total number of results in the set
  • The limit and start properties are the parameters used to make this call
  • prev is the URL of the previous page of results. If at the first page of results, this value will be null.
  • self is the URL of the current request that was just made
  • next is the URL of the next page of results. If at the last page of results, this value will be null.

So to get all results in a collection, you can begin with start=0 for your first request. Then, if there is a value for next, use this URL for your next request. Repeat this process until the next value is null, which means you're at the final page of results.

Error Object

If a request was invalid or there was a problem with the response, the server will respond with an error object describing the issue.

For example, if you make a request with a begin date of October 1st, 2015 and an end date of September 30, 2015 you'll receive the following response along with an HTTP 422 response code:

{
  "error": {
    "code": 10012,
    "message": "Begin date must be before end date",
    "description": "The requested date range is not valid. The begin date must be before the end date."
  }
}
Did this answer your question?