Table of Contents

    API

    Transparent Proxy

    Please sign in and we'll assign you a private URL to trace your traffic and help you implement the API.

AuthorityLabs Interface API RC1 (beta)

The AuthorityLabs Interface API allows you to interact with your AuthorityLabs-tracked domains and keywords, similar to the web interface. To access the api, you will need to provide your account API key as a custom HTTP header.

  • Any routes that accept date parameters are fairly flexible. Examples of valid date formats are 2013-11-08 or Nov-08-2013.
  • All API requests are within the context of your AuthorityLabs account, based on your unique API key and account domain
  • The Interface API is rate-limited. This means that you will have a limited number of overall requests per hour. Contact AuthorityLabs Support for more information on this.
  • Your current hourly rate limit is returned in each API response header and can also be found in your AuthorityLabs account page.

Additional Notes

  • The URL routes documented below are subject to change during the beta period of the Interface API.
  • CORS (cross-origin resource sharing) requests are not supported at this time in the Interface API.
  • If using curl, please be sure to wrap the URL in quotation marks. Without quotes, you may encounter odd behavior such as truncated JSON responses.

Domain Group Resources

The following is a section of requests related to domain groups within your account

GET

/api/groups

List all domain groups

Response

200 (OK)
Content-Type: application/json
{ 
    "groups": [
        {
            "id": 21,
            "name": "Test Group",
            "is_synced": true,
            "is_syncing": false
        },
        {
            "id": 20,
            "name": "Example Group",
            "is_synced": false,
            "is_syncing": false
        }
    ]
}

GET

/api/groups/{group_id}

Retrieve a specific domain group

Response

200 (OK)
Content-Type: application/json
{
    "group": {
        "id": 21,
        "name": "Test Group",
        "is_synced": true,
        "is_syncing": false
    }
}

Response

404 (Not Found)
Content-Type: application/json
{
    "message": "Group not found"
}

Domain Resources

The following is a section of requests related to domains within your account

GET

/api/groups/{group_id}/domains

List domains within a specific domain group

Response

200 (OK)
Content-Type: application/json
{
    "domains": [
        {
            "id": 45,
            "url": "canadatest.com",
            "header_status": 200,
            "is_new_domain": false,
            "is_user_favorite": false,
            "group_id": 2,
            "locale_id": 6,
            "city_id": null,
            "tag_ids": [3, 8],
            "display_engines": [
                "google",
                "yahoo",
                "bing"
            ],
            "keyword_count": 3,
            "created_at": "2013-08-23T19:06:56Z",
            "updated_at": "2013-09-23T20:11:35Z"
        },
        {
            "id": 39,
            "url": "example.com",
            "header_status": 200,
            "is_new_domain": false,
            "is_user_favorite": false,
            "group_id": 2,
            "locale_id": 14,
            "city_id": null,
            "tag_ids": [],
            "display_engines": [
                "google",
                "yahoo",
                "bing"
            ],
            "keyword_count": 3,
            "created_at": "2013-08-23T19:06:56Z",
            "updated_at": "2013-09-23T19:06:56Z"
        }
    ]
}

GET

/api/domains

List all domains

Response

200 (OK)
Content-Type: application/json
{
    "domains": [
        {
            "id": 45,
            "url": "canadatest.com",
            "header_status": 200,
            "is_new_domain": false,
            "is_user_favorite": false,
            "group_id": null,
            "locale_id": 6,
            "city_id": null,
            "tag_ids": [4],
            "display_engines": [
                "google",
                "yahoo",
                "bing"
            ],
            "keyword_count": 3,
            "created_at": "2013-08-23T19:06:56Z",
            "updated_at": "2013-09-23T20:11:35Z"
        },
        {
            "id": 39,
            "url": "example.com",
            "header_status": 200,
            "is_new_domain": false,
            "is_user_favorite": false,
            "group_id": 20,
            "locale_id": 14,
            "city_id": null,
            "tag_ids": [],
            "display_engines": [
                "google",
                "yahoo",
                "bing"
            ],
            "keyword_count": 3,
            "created_at": "2013-08-23T19:06:56Z",
            "updated_at": "2013-09-23T19:06:56Z"
        }
    ]
}

GET

/api/domains/{domain_id}

Retrieve a specific domain

Response

200 (OK)
Content-Type: application/json
{
    "domain": {
        "id": 44,
        "url": "test.net",
        "city_id": 1,
        "group_id": 21,
        "locale_id": 14,
        "tag_ids": [1, 3, 19],
        "display_engines": [
            "google",
            "yahoo",
            "bing"
        ],
        "keyword_count": 2,
        "header_status": 200,
        "is_new_domain": false,
        "is_user_favorite": false,
        "created_at": "2013-08-23T19:06:56Z",
        "updated_at": "2013-09-23T19:06:56Z"
    },
    "city": [
        {
            "active": true,
            "bing": false,
            "created_at": "2013-05-13T18:52:23Z",
            "google": true,
            "id": 1,
            "lat": null,
            "lng": null,
            "name": "Phoenix",
            "state_abbr": "AZ",
            "state_full": "Arizona",
            "updated_at": "2013-05-13T18:52:23Z",
            "yahoo": false,
            "zip": "85001",
            "value": "Phoenix, AZ 85001"
        }
    ],
    "group": [
        {
            "id": 21,
            "name": "Test Group",
            "is_syncing": false,
            "is_synced": true
        }
    ],
    "locale": [
        {
            "active": true,
            "bing": true,
            "description": "United States - English",
            "google": true,
            "id": 14,
            "name": "en-us",
            "yahoo": true,
            "value": "United States - English"
        }
    ]
}

Response

404 (Not Found)
Content-Type: application/json
{
    "message": "Domain not found"
}

Domain Rank Average Resource

A Domain's Average Rank can be found as a nested resource under individual domains

GET

/api/rank_averages?domain_id={domain_id}

Retrieve the domain's rank average for the current day

Response

200 (OK)
Content-Type: application/json
{
    "rankAverages": [{
        "bing_90_day_avgs": [88, 90, 90, 89, 94, 90, 85, 83, 85, 86, 85, 84, 86, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101],
        "bing_avg": 88,
        "bing_initial_avg": 101,
        "google_90_day_avgs": [32, 33, 33, 37, 36, 43, 42, 42, 42, 42, 39, 37, 38, 41, 36, 36, 36, 39, 44, 41, 34, 40, 43, 41, 43, 39, 39],
        "google_avg": 32,
        "google_initial_avg": 39,
        "has_bing_avg": true,
        "has_google_avg": true,
        "has_yahoo_avg": true,
        "yahoo_90_day_avgs": [92, 95, 95, 95, 97, 95, 93, 92, 93, 93, 93, 94, 94, 90, 93, 91, 91, 91, 87, 87, 87, 87, 87, 87, 83, 84, 84],
        "yahoo_avg": 92,
        "yahoo_initial_avg": 84,
        "domain_id": 121684,
        "rank_date": 20131217,
        "id": "121684:20131217"
    }]
}

GET

/api/rank_averages?domain_id={domain_id}&rank_date={rank_date}

Retrieve the domain's rank average for a specific date

Response

200 (OK)
Content-Type: application/json
{
    "rankAverages": [{
        "bing_90_day_avgs": [88, 90, 90, 89, 94, 90, 85, 83, 85, 86, 85, 84, 86, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101],
        "bing_avg": 88,
        "bing_initial_avg": 101,
        "google_90_day_avgs": [32, 33, 33, 37, 36, 43, 42, 42, 42, 42, 39, 37, 38, 41, 36, 36, 36, 39, 44, 41, 34, 40, 43, 41, 43, 39, 39],
        "google_avg": 32,
        "google_initial_avg": 39,
        "has_bing_avg": true,
        "has_google_avg": true,
        "has_yahoo_avg": true,
        "yahoo_90_day_avgs": [92, 95, 95, 95, 97, 95, 93, 92, 93, 93, 93, 94, 94, 90, 93, 91, 91, 91, 87, 87, 87, 87, 87, 87, 83, 84, 84],
        "yahoo_avg": 92,
        "yahoo_initial_avg": 84,
        "domain_id": 121684,
        "rank_date": 20131217,
        "id": "121684:20131217"
    }]
}

Domain Locale Resource

GET

/api/domains/{domain_id}/locale

Retrieve the locale information for a specific domain

Response

200 (OK)
Content-Type: application/json
{
    "locale": {
        "id": 14,
        "name": "en-us",
        "description": "United States - English",
        "google": true,
        "yahoo": true,
        "bing": true,
        "active": true
    }
}

Domain City Resource

GET

/api/domains/{domain_id}/city

Retrieve the city information for a specific domain

Response

200 (OK)
Content-Type: application/json
{
    "city": {
        "id": 1,
        "name": "Phoenix",
        "state_full": "Arizona",
        "state_abbr": "AZ",
        "zip": "85001"
    }
}

Response

404 (Not Found)
Content-Type: application/json
{
    "message": "City not found"
}

Domain Tags Resource

GET

/api/domains/{domain_id}/tags

Retrieve any tags present for a specific domain

Response

200 (OK)
Content-Type: application/json
{
    "tags": [
        {
            "id": 53,
            "name": "85001"
        },
        {
            "id": 55,
            "name": "Phoenix"
        },
        {
            "id": 54,
            "name": "tagged domains"
        },
        {
            "id": 1,
            "name": "test"
        }
    ]
}

Keyword Resources

The following is a section of requests related to keywords within your account

GET

/api/domains/{domain_id}/keywords

List keywords within a specific domain

Response

200 (OK)
Content-Type: application/json
{
    "keywords": [
        {
            "id": 556,
            "name": "example keyword 3",
            "domain_id": 40,
            "is_new_keyword": false,
            "total_words": 3,
            "volume": "277",
            "created_at": "2013-09-23T18:23:31Z",
            "updated_at": "2013-09-23T18:23:31Z",
            "keyword_tags": [
                57
            ]
        },
        {
            "id": 557,
            "name": "example keyword 4",
            "domain_id": 40,
            "is_new_keyword": false,
            "total_words": 3,
            "volume": "1841",
            "created_at": "2013-09-23T18:23:31Z",
            "updated_at": "2013-09-23T18:23:31Z",
            "keyword_tags": [
                57
            ]
        },
        {
            "id": 558,
            "name": "examples",
            "domain_id": 40,
            "is_new_keyword": false,
            "total_words": 1,
            "volume": "800",
            "created_at": "2013-09-23T18:23:31Z",
            "updated_at": "2013-09-23T18:23:31Z",
            "keyword_tags": [
                58,
                61
            ]
        }
    ]
}

GET

/api/keywords/{keyword_id}

Retrieve a specific keyword

Response

200 (OK)
Content-Type: application/json
{
    "keyword": {
        "id": 556,
        "name": "example keyword 3",
        "domain_id": 40,
        "total_words": 3,
        "volume": "277",
        "created_at": "2013-09-23T18:23:31Z",
        "updated_at": "2013-09-23T18:23:31Z"
    }
}

POST

/api/domains/{domain_id}/keywords

Create a new keyword for an existing domain

Response

201 (Created)
Content-Type: application/json
{
    "message": "Keyword created",
    "_ref": "/api/keywords/561"
}

Response

409 (Conflict)
Content-Type: application/json
{
    "message": "Keyword already exists for this domain."
}

Keyword Rank Resource

A Keyword Rank can be found as a nested resource under individual keywords

GET

/api/ranks?keyword_id={keyword_id}

Retrieve the keyword rank for the current day

Response

200 (OK)
Content-Type: application/json
{
    "ranks": [
        {
            "domain_id": 39,
            "keyword_id": 553,
            "locale_id": 14,
            "rank_date": 20130904,
            "google_change": -1,
            "google_initial_rank": 28,
            "google_rank": 30,
            "google_ranks": {
                "30": "http://ranked-domain.com/30",
                "31": "http://ranked-domain.com/31"
            },
            "google_90_day_history": [
                30,
                29,
                28,
                33,
                13,
                7,
                20,
                18,
                7,
                25,
                10,
                20,
                28
            ],
            "yahoo_change": 18,
            "yahoo_initial_rank": 11,
            "yahoo_rank": 12,
            "yahoo_ranks": {
                "12": "http://ranked-domain.com/12",
                "15": "http://ranked-domain.com/15"
            },
            "yahoo_90_day_history": [
                12,
                30,
                11,
                9,
                4,
                34,
                25,
                21,
                17,
                25,
                11,
                30,
                11
            ],
            "bing_change": -14,
            "bing_initial_rank": 35,
            "bing_rank": 30,
            "bing_ranks": {
                "30": "http://ranked-domain.com/30",
                "47": "http://ranked-domain.com/47"
            },
            "bing_90_day_history": [
                30,
                16,
                28,
                33,
                34,
                20,
                31,
                25,
                13,
                25,
                3,
                2,
                35
            ],
            "google_total_results": 1000000,
            "yahoo_total_results": 1000000,
            "bing_total_results": 1000000,
            "brand": false,
            "local_pack": true,
            "local_rank": 3,
            "blog": false,
            "news": true,
            "images": true,
            "shopping": true,
            "micro_format": true,
            "video": true,
            "id": "39:553:20130904",
            "has_google_rank": true,
            "has_yahoo_rank": true,
            "has_bing_rank": true
        }
    ]
}

GET

/api/ranks?keyword_id={keyword_id}&rank_date={rank_date}

Retrieve the keyword rank for a specific date

Response

200 (OK)
Content-Type: application/json
{
    "ranks": [
        {
            "domain_id": 39,
            "keyword_id": 553,
            "locale_id": 14,
            "rank_date": 20130901,
            "google_change": -20,
            "google_initial_rank": 28,
            "google_rank": 33,
            "google_ranks": {
                "33": "http://ranked-domain.com/33",
                "35": "http://ranked-domain.com/35"
            },
            "google_90_day_history": [
                33,
                13,
                7,
                20,
                18,
                7,
                25,
                10,
                20,
                28
            ],
            "yahoo_change": -5,
            "yahoo_initial_rank": 11,
            "yahoo_rank": 9,
            "yahoo_ranks": {
                "9": "http://ranked-domain.com/9",
                "15": "http://ranked-domain.com/15"
            },
            "yahoo_90_day_history": [
                9,
                4,
                34,
                25,
                21,
                17,
                25,
                11,
                30,
                11
            ],
            "bing_change": 1,
            "bing_initial_rank": 35,
            "bing_rank": 33,
            "bing_ranks": {
                "33": "http://ranked-domain.com/33",
                "48": "http://ranked-domain.com/48"
            },
            "bing_90_day_history": [
                33,
                34,
                20,
                31,
                25,
                13,
                25,
                3,
                2,
                35
            ],
            "google_total_results": 1000000,
            "yahoo_total_results": 1000000,
            "bing_total_results": 1000000,
            "brand": false,
            "local_pack": true,
            "local_rank": 2,
            "blog": false,
            "news": true,
            "images": true,
            "shopping": true,
            "micro_format": true,
            "video": true,
            "id": "39:553:20130901",
            "has_google_rank": true,
            "has_yahoo_rank": true,
            "has_bing_rank": true
        }
    ]
}

Keyword Tags Resource

GET

/api/keywords/{keyword_id}/tags

Retrieve any tags present for a specific keyword

Response

200 (OK)
Content-Type: application/json
{
    "tags": [
        {
            "id": 61,
            "name": "a keyword tag"
        },
        {
            "id": 58,
            "name": "important"
        }
    ]
}