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",
"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>'
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": {
"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>'
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",
"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>'
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,
"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>'
Response
{
"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>'
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)