1. Ad Methods
    2. adTerms

    adTerms

    This method returns suggestions for terms found in ads. Results can be filtered by using query parameters. This method is handy for implementing auto-completion form elements in your web application's UI.

    Request Cost: 25 units, Result Cost: 1 unit/result

    URL Format

    http://api.adbeat.com/v3/{api-key}/adTerms

    Parameters

    Parameter Name Meaning Default Value Notes
    q query (required) No wildcards needed or used - e.g. lug will find travel luggage as a suggestion.
    countryId country filter (no filtering)
    e.g. us (See countries)
    platformId platform filter (no filtering) e.g. desktop (See platforms) To specify multiple values, separate them by commas (e.g. iPhone,iPad) Currently only desktop is supported for a non-us countryId. Use &platformId=mobile to specify all mobile devices (i.e. android, iphone, ipad, androidtablet)
    rows Number of results to return 10 Maximum 100
    start Index of first result to return 0 Use start=N (where N > 0) to page through results by making repeated requests.
    fields fields filter (no filtering) Restrict which fields get returned. e.g. &fields=suggestion would return just one of the available fields. &fields=suggestion,score would return just two of the available fields.

    Return Fields

    Note: The following fields are returned except for certain query parameter filters. (See Response Format)
    Field Name Example Notes
    countryId us
    platformId desktop
    suggestion travel luggage Suggested term for the provided query.
    score 14 Score of result, based on popularity of the term and other factors.
    apiUnits 35 The number of API units consumed by this request.

    Usage Example(s)

    To find suggestions that contain insurance do this:

    http://api.adbeat.com/v3/{api-key}/adTerms/?q=insurance

    JSON Response

    {
    "statusCode": 200,
    "numHits": 19880,
    "hits": [{
        "countryId": "us",
        "score": 142745,
        "suggestion": "insurance",
        "platformId": "desktop"
    }, {
        "countryId": "us",
        "score": 26023,
        "suggestion": "insurance",
        "platformId": "ipad"
    }, {
        "countryId": "us",
        "score": 25995,
        "suggestion": "insurance",
        "platformId": "android"
    }, {
        "countryId": "us",
        "score": 22183,
        "suggestion": "insurance",
        "platformId": "iphone"
    }, {
        "countryId": "gb",
        "score": 20406,
        "suggestion": "insurance",
        "platformId": "desktop"
    }, {
        "countryId": "us",
        "score": 19150,
        "suggestion": "insurance",
        "platformId": "androidtablet"
    }, {
        "countryId": "us",
        "score": 12717,
        "suggestion": "car insurance",
        "platformId": "desktop"
    }, {
        "countryId": "ca",
        "score": 10818,
        "suggestion": "insurance",
        "platformId": "desktop"
    }, {
        "countryId": "au",
        "score": 7721,
        "suggestion": "insurance",
        "platformId": "desktop"
    }, {
        "countryId": "us",
        "score": 5758,
        "suggestion": "auto insurance",
        "platformId": "desktop"
    }],
    "apiUnits": 35,
    "statusMsg": "successful adTerms request",
    "requestParameters": {
        "q": "insurance"
    },
    "handler": "adTerms"
}

    You can also use parameters to get more specific and detailed results. To find suggestions that contain weight, limit the results to the us, and return 20 rows of data instead of the default 10 rows, do this:

    http://api.adbeat.com/v3/{api-key}/adTerms/?q=weight&countryId=us&rows=20

    JSON Response

    {
    "statusCode": 200,
    "numHits": 7867,
    "hits": [{
        "score": 72896,
        "suggestion": "weight",
        "platformId": "desktop"
    }, {
        "score": 16088,
        "suggestion": "weight",
        "platformId": "android"
    }, {
        "score": 14937,
        "suggestion": "weight",
        "platformId": "ipad"
    }, {
        "score": 14221,
        "suggestion": "weight",
        "platformId": "iphone"
    }, {
        "score": 11464,
        "suggestion": "weight",
        "platformId": "androidtablet"
    }, {
        "score": 6314,
        "suggestion": "weight loss",
        "platformId": "desktop"
    }, {
        "score": 5534,
        "suggestion": "lose weight",
        "platformId": "desktop"
    }, {
        "score": 1762,
        "suggestion": "weight loss",
        "platformId": "android"
    }, {
        "score": 1619,
        "suggestion": "weight loss",
        "platformId": "ipad"
    }, {
        "score": 1581,
        "suggestion": "weight loss",
        "platformId": "iphone"
    }, {
        "score": 1558,
        "suggestion": "lose weight",
        "platformId": "android"
    }, {
        "score": 1394,
        "suggestion": "lose weight",
        "platformId": "iphone"
    }, {
        "score": 1288,
        "suggestion": "weight loss",
        "platformId": "androidtablet"
    }, {
        "score": 1210,
        "suggestion": "lose weight",
        "platformId": "ipad"
    }, {
        "score": 1134,
        "suggestion": "weightloss",
        "platformId": "desktop"
    }, {
        "score": 983,
        "suggestion": "lose weight",
        "platformId": "androidtablet"
    }, {
        "score": 784,
        "suggestion": "weight loss today",
        "platformId": "desktop"
    }, {
        "score": 778,
        "suggestion": "weight fast",
        "platformId": "desktop"
    }, {
        "score": 768,
        "suggestion": "weight loss surgery",
        "platformId": "desktop"
    }, {
        "score": 763,
        "suggestion": "weight-loss",
        "platformId": "desktop"
    }],
    "apiUnits": 45,
    "statusMsg": "successful adTerms request",
    "requestParameters": {
        "countryId": "us",
        "q": "weight",
        "rows": "20"
    },
    "handler": "adTerms"
}