SEO API v1

Changelog

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

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

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)