Table of Contents

    API

    Mock Server

    Use this URL to access a mockup of the API server. Your traffic will be recorded and compared to the documentation. You'll find your traffic analysis in the inspector or directly here in the documentation, right next to each resource.

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"
        }
    ]
}