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,
    "engine": "www.google.com",
    "region": "United States",
    "keywords": [
        {
            "id": 1,
            "name": "example",
            "region": "Los Angeles,California",
            "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

Get campaign serp links

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

Get competitor serp links

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

Get group serp links

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)