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'

{
    "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'

[
    {
        "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>'

{
    "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",
            "avg": 56.0,
            "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 keyword buckets

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

{
    "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": {
        "1_3": [
            {
                "id": 1,
                "name": "example_1",
                "region": "Los Angeles,California"
            },
            {
                "id": 2,
                "name": "example_2",
                "region": "Los Angeles,California"
            }
        ],
        "4_10": [
            {
                "id": 3,
                "name": "example_3",
                "region": "Los Angeles,California"
            },
        ],
        "101_inf": [
            {
                "id": 4,
                "name": "example_4",
                "region": "Los Angeles,California"
            }
        ]
    }
}

This endpoint retrieves campaign keywords grouped by position (buckets). The position buckets are 1-3, 4-10, 11-13, 14-30, 31-100, 101+. Maximum date range is 31 days. Keyword will be assigned to the bucket according to it’s best position in given date range.

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>'

{
    "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>'

{
    "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'

[
  {
      "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>'

{
    "id": 1,
    "name": "example.com",
    "mobile": false,
    "date_from": 2017-05-12,
    "date_to": 2017-05-16,
    "keywords": [
        {
            "id": 1,
            "name": "example",
            "avg": 56.0,
            "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>'

{
    "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'

[
    {
        "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'

[
    {
        "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>'

{
    "id": 1,
    "name": "example group",
    "mobile": false,
    "date_from": 2017-05-12,
    "date_to": 2017-05-16,
    "engine": "www.google.com",
    "region": "United States",
    "keywords": [
        {
            "id": 1,
            "name": "example",
            "avg": 56.0,
            "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 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 keyword buckets

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

{
    "id": 1,
    "name": "example group",
    "mobile": false,
    "date_from": 2017-05-12,
    "date_to": 2017-05-16,
    "engine": "www.google.com",
    "region": "United States",
    "keywords": {
        "1_3": [
            {
                "id": 1,
                "name": "example_1",
                "region": "Los Angeles,California"
            },
            {
                "id": 2,
                "name": "example_2",
                "region": "Los Angeles,California"
            }
        ],
        "4_10": [
            {
                "id": 3,
                "name": "example_3",
                "region": "Los Angeles,California"
            },
        ],
        "101_inf": [
            {
                "id": 4,
                "name": "example_4",
                "region": "Los Angeles,California"
            }
        ]
    }
}

This endpoint retrieves group keywords grouped by position (buckets). The position buckets are 1-3, 4-10, 11-13, 14-30, 31-100, 101+. Maximum date range is 31 days. Keyword will be assigned to the bucket according to it’s best position in given date range.

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>'

{
    "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'

[
    {
        "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'

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

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