NAV
shell
documentation

SEO API v1

Changelog

11.06.2019

Added new endpoint for obtaining search volume for keywords within given campaign.

04.09.2017

Added three new endpoints for obtaining serp urls for keywords within given campaign/group/competitor.

12.06.2017

Initial release of Unamo SEO public API.

Get Started

Please keep in mind that requests limit is set to 15 requests/second.

Authorization

To authorize, use your personal access token that you can obtain from API section in our platform.

curl 'https://seo.unamo.com/api/v1?token=myuniquetoken'
# or
curl -H 'Token: myuniquetoken' 'https://seo.unamo.com/api/v1'

Response:

{
    "account": {
        "id": 1,
        "name": "Name",
        "created_at": "2017-06-01T13:04:10.861Z"
    },
    "user": {
        "id": 1,
        "name": "Name",
        "created_at": "2017-06-01T13:04:10.861Z"
    }
}

Campaigns

Get all campaigns

curl 'https://seo.unamo.com/api/v1/campaigns.json'

Response:

[
    {
        "id": 1,
        "account_id": 1,
        "name": "example.com",
        "title": "Example",
        "active": true,
        "created_at": "2016-02-22T16:27:23.400Z"
    }
]

This endpoint retrieves all campaigns.

Get campaign positions

curl 'https://seo.unamo.com/api/v1/campaigns/CAMPAIGN_ID/positions.json?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&mobile=<true|false>'

Response

{
    "id": 1,
    "name": "example.com",
    "mobile": false,
    "date_from": 2017-05-12,
    "date_to": 2017-05-16,
    "keywords": [
        {
            "id": 1,
            "name": "example",
            "positions": {
                "2017-05-12": 66,
                "2017-05-13": 50,
                "2017-05-14": 72,
                "2017-05-15": 38,
                "2017-05-16": 54
            }
        }
    ]
}

This endpoint retrieves campaign positions. Maximum date range is 31 days.

Required parameters:

Parameter Description Type
date_from Position start date Date as a string in YYYY-MM-DD format
date_to Position end date Date as a string in YYYY-MM-DD format

Optional parameters:

Parameter Description Type
mobile Get results for mobile Boolean value true / false
curl 'https://seo.unamo.com/api/v1/campaigns/CAMPAIGN_ID/serp_links.json?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&mobile=<true|false>'

Response

{
    "id": 1,
    "name": "example.com",
    "mobile": false,
    "date_from": 2017-05-12,
    "date_to": 2017-05-16,
    "keywords": [
        {
            "id": 1,
            "name": "example",
            "serp_links": {
                "2017-05-12": "http://example.com",
                "2017-05-13": "http://example.com",
                "2017-05-14": "http://example.com/subpage",
                "2017-05-15": "http://example.com",
                "2017-05-16": "http://example.com/blog"
            }
        }
    ]
}

This endpoint retrieves campaign serp urls. Maximum date range is 31 days.

Required parameters:

Parameter Description Type
date_from Start date Date as a string in YYYY-MM-DD format
date_to End date Date as a string in YYYY-MM-DD format

Optional parameters:

Parameter Description Type
mobile Get results for mobile Boolean value true / false

Get campaign search volumes

curl 'https://seo.unamo.com/api/v1/campaigns/CAMPAIGN_ID/search_volumes.json?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&mobile=<true|false>'

Response

{
    "id": 1,
    "name": "example.com",
    "mobile": false,
    "date_from": 2017-05-12,
    "date_to": 2017-05-16,
    "keywords": [
        {
            "id": 1,
            "name": "example",
            "search_volumes": {
                "2017-05-12": 10,
                "2017-05-13": 20,
                "2017-05-14": 30,
                "2017-05-15": 15,
                "2017-05-16": 13
            }
        }
    ]
}

This endpoint retrieves campaign search volumes. Maximum date range is 31 days.

Required parameters:

Parameter Description Type
date_from Start date Date as a string in YYYY-MM-DD format
date_to End date Date as a string in YYYY-MM-DD format

Optional parameters:

Parameter Description Type
mobile Get results for mobile Boolean value true / false

Competitors

Get all competitors

curl 'https://seo.unamo.com/api/v1/campaigns/CAMPAIGN_ID/competitors.json'

Response:

[
  {
      "id": 15,
      "name": "https://exaple_competitor.com",
      "title": "exaple_competitor.com",
      "created_at": "2016-02-22T16:27:23.400Z"
  }
]

This endpoint retrieves all website competitors.

Get competitor positions

curl 'https://seo.unamo.com/api/v1/campaigns/CAMPAIGN_ID/competitors/COMPETITOR_ID/positions.json?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&mobile=<true|false>'

Response

{
    "id": 1,
    "name": "example.com",
    "mobile": false,
    "date_from": 2017-05-12,
    "date_to": 2017-05-16,
    "keywords": [
        {
            "id": 1,
            "name": "example",
            "positions": {
                "2017-05-12": 66,
                "2017-05-13": 50,
                "2017-05-14": 72,
                "2017-05-15": 38,
                "2017-05-16": 54
            }
        }
    ]
}

This endpoint retrieves competitor positions. Maximum date range is 31 days.

Required parameters:

Parameter Description Type
date_from Position start date Date as a string in YYYY-MM-DD format
date_to Position end date Date as a string in YYYY-MM-DD format

Optional parameters:

Parameter Description Type
mobile Get results for mobile Boolean value true / false
curl 'https://seo.unamo.com/api/v1/campaigns/CAMPAIGN_ID/competitors/COMPETITOR_ID/serp_links.json?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&mobile=<true|false>'

Response

{
    "id": 1,
    "name": "example.com",
    "mobile": false,
    "date_from": 2017-05-12,
    "date_to": 2017-05-16,
    "keywords": [
        {
            "id": 1,
            "name": "exampl",
            "serp_links": {
                "2017-05-12": "http://example.com",
                "2017-05-13": "http://example.com",
                "2017-05-14": "http://example.com/subpage",
                "2017-05-15": "http://example.com",
                "2017-05-16": "http://example.com/blog"
            }
        }
    ]
}

This endpoint retrieves competitor serp links. Maximum date range is 31 days.

Required parameters:

Parameter Description Type
date_from Start date Date as a string in YYYY-MM-DD format
date_to End date Date as a string in YYYY-MM-DD format

Optional parameters:

Parameter Description Type
mobile Get results for mobile Boolean value true / false

Keywords

Get all keywords

curl 'https://seo.unamo.com/api/v1/campaigns/CAMPAIGN_ID/keywords.json'

Response:

[
    {
        "id": 1,
        "group_id": [1, 2],
        "website_id": 1,
        "name": "example",
        "created_at": "2016-02-22T16:27:23.400Z"
    }
]

This endpoint retrieves all keywords.

Groups

Get all groups

curl 'https://seo.unamo.com/api/v1/campaigns/CAMPAIGN_ID/groups.json'

Response:

[
    {
        "id": 1,
        "website_id": 1,
        "name": "Example",
        "created_at": "2017-05-17T00:40:17+02:00"
    }
]

This endpoint retrieves all groups.

Get group positions

curl 'https://seo.unamo.com/api/v1/campaigns/CAMPAIGN_ID/groups/GROUP_ID/positions.json?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&mobile=<true|false>'

Response

{
    "id": 1,
    "name": "example group",
    "mobile": false,
    "date_from": 2017-05-12,
    "date_to": 2017-05-16,
    "keywords": [
        {
            "id": 1,
            "name": "example",
            "positions": {
                "2017-05-12": 66,
                "2017-05-13": 50,
                "2017-05-14": 72,
                "2017-05-15": 38,
                "2017-05-16": 54
            }
        }
    ]
}

This endpoint retrieves group positions. Maximum date range is 31 days.

Required parameters:

Parameter Description Type
date_from Position start date Date as a string in YYYY-MM-DD format
date_to Position end date Date as a string in YYYY-MM-DD format

Optional parameters:

Parameter Description Type
mobile Get results for mobile Boolean value true / false
curl 'https://seo.unamo.com/api/v1/campaigns/CAMPAIGN_ID/groups/GROUP_ID/serp_links.json?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&mobile=<true|false>'

Response

{
    "id": 1,
    "name": "example group",
    "mobile": false,
    "date_from": 2017-05-12,
    "date_to": 2017-05-16,
    "keywords": [
        {
            "id": 1,
            "name": "example",
            "serp_links": {
                "2017-05-12": "http://example.com",
                "2017-05-13": "http://example.com",
                "2017-05-14": "http://example.com/subpage",
                "2017-05-15": "http://example.com",
                "2017-05-16": "http://example.com/blog"
            }
        }
    ]
}

This endpoint retrieves group serp links. Maximum date range is 31 days.

Required parameters:

Parameter Description Type
date_from Start date Date as a string in YYYY-MM-DD format
date_to End date Date as a string in YYYY-MM-DD format

Optional parameters:

Parameter Description Type
mobile Get results for mobile Boolean value true / false

Engines

Get engines

curl 'https://seo.unamo.com/api/v1/engines/<google|yahoo|bing|yandex>.json'

Response:

[
    {
        "id": 1,
        "domain": "www.google.com.ar",
        "provider": "Google",
        "created_at": "2017-05-17T00:40:17+02:00",
        "language_name": "español (Latinoamérica)",
        "language_code": "es"
    },
    {
        "id": 2,
        "domain": "www.google.com.au",
        "provider": "Google",
        "created_at": "2017-05-17T00:40:17+02:00",
        "language_name": "English",
        "language_code": "en"
    }
]

This endpoint retrieves engines that are accessible in Unamo SEO.

Regions

Get engine regions

curl 'https://seo.positionly.com/api/v1/engines/<engine_id>/regions.json'

Response:

[
    {
        "id": 1,
        "name": "Cordova,Alaska"
    },
    {
        "id": 2,
        "name": "Valley,Alabama"
    }
]

This endpoint retrieves regions associated with given engine (if any)