1. Response Format

    Response Format

    Responses are returned in JSON format. This page give detailed information about the various fields the Adbeat API methods return.

    Response Headers

    Every response has a header with the same set of fields:

    Field Name Example Meaning
    statusCode 200 200 is no error, otherwise it's some other HTTP status code. See "Errors" for more info.
    statusMsg successful ads request Response message useful for debugging, not be be displayed to end users
    handler adMetrics Handler (method used) from request path
    requestParameters 
    {
    "advertiserId":"cnn.com",
    "countryId":"us"
}
    		Array of request parameters, each with its value. This typically also includes the target from the request path.
    apiUnits 100 The number of API units consumed by this request.

    Hit Arrays

    When a method returns an array hits, these fields are also included:

    Field Name Example Meaning
    numHits 1 Total number of results.  This may be greater than the size of the hits array if the method supports pagination.
    hits 
    [
    {
        <hit 1>
    }, 
    {
        <hit 2>
    },
    {
        <hit 3>
    }
]
    		Array of records, one per hit. This will be an empty array if numHits == 0.

    Omitted Fields

    When query parameters are used to filter fields, these fields will not be included in the hit records. This is because each hit would contain the same value for this field.

    The same rule applies to dates. When you make a request that filters/restricts results to a specific date, the date related fields (e.g. firstSeen) are not returned in the hit array. Again, this is because all of the dates would be the same value.

    However, when passing a date range (See Date Formats), date related fields ARE returned for each element in the hit array.

    To better clarify this behavior, let's look at a couple of examples:

    Example #1

    This request to the /advertisers method DOES NOT specify &countryId

    http://api.adbeat.com/v3/{api-key}/advertisers/?q=ace&rows=2

    JSON Response

    Since &countryId was not specified, the countryId is returned for each element in the hit array.

    {
    "statusCode": 200,
    "numHits": 2554,
    "hits": [{
        "countryId": "us",
        "score": 597,
        "suggestion": "ace-pt.org",
        "platformId": "desktop"
    }, {
        "countryId": "us",
        "score": 524,
        "suggestion": "acehardware.com",
        "platformId": "desktop"
    }],
    "apiUnits": 27,
    "statusMsg": "successful advertisers request",
    "requestParameters": {
        "q": "ace",
        "rows": "2"
    },
    "handler": "advertisers"
}

    Example #2

    This request to the /advertisers method DOES specify &countryId

    http://api.adbeat.com/v3/{api-key}/advertisers/?q=ace&countryId=gb&rows=2

    JSON Response

    Since &countryId was specified, the countryId is NOT returned for each element in the hit array. (Because it would be the same value for every element in the array.)

    {
    "statusCode": 200,
    "numHits": 172,
    "hits": [{
        "score": 99,
        "suggestion": "acesec.co.uk",
        "platformId": "desktop"
    }, {
        "score": 65,
        "suggestion": "aceonline.co.uk",
        "platformId": "desktop"
    }],
    "apiUnits": 27,
    "statusMsg": "successful advertisers request",
    "requestParameters": {
        "countryId": "gb",
        "q": "ace",
        "rows": "2"
    },
    "handler": "advertisers"
}