API v2
Get Started
Please keep in mind that requests limit is set to 15 requests/second.
Authorization
To authorize, use this code:
curl -X POST -d
'grant_type=password&username=USER_EMAIL&password=YOUR_PASSWORD&client_id=de3be2752e8ae27a11cd96a6b0999b0f&client_secret=8d87664221c09681c3d3bc283a50bf73'
'https://auth.positionly.com/oauth2/token'
Response:
{
"access_token": "37e120ae8ae9752105079bb28f07cfff",
"token_type": "bearer",
"expires_in": 3599,
"refresh_token": "6b6f99496dde0faf947e8b964360d2e7"
}
OAuth2
Client ID:
de3be2752e8ae27a11cd96a6b0999b0fClient secret:
8d87664221c09681c3d3bc283a50bf73
Refresh token
curl -X POST -d'grant_type=refresh_token&client_id=de3be2752e8ae27a11cd96a6b0999b0f&client_secret=8d87664221c09681c3d3bc283a50bf73&refresh_token=YOUR_REFRESH_TOKEN' 'https://auth.positionly.com/oauth2/token'
Response:
{
"access_token": "1eb14d5bd9d51af6f398ca2cd9b0fbcf",
"token_type": "bearer",
"expires_in": 3599,
"refresh_token": "6b6f99496dde0faf947e8b964360d2e7"
}
You’ll know when you have to refresh your token by looking at expires_in field. If you’re getting an unauthorized access error it may also mean that your token has expired. You can refresh token that is not expired.
Usage example
curl -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.positionly.com/v2/...'
or
curl https://api.positionly.com/v2/...?access_token=ACCESS_TOKEN
Accounts
Get all accounts
curl https://api.positionly.com/v2/accounts.json
Response:
[
{
"id": 1,
"name": "Example",
"full_domain": "example.positionly.com",
"created_at": "2012-09-17T00:40:18+02:00"
},
<...>
]
This endpoint retrieves all accounts.
Get a specific account
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID.json
The above command returns JSON structured like this:
{
"id": 1,
"name": "Example",
"full_domain": "example.positionly.com",
"created_at": "2012-09-17T00:40:18+02:00",
"websites": [
{
"id": 1,
"account_id": 1,
"name": "https://example.com",
"title": "Example"
},
<...>
]
}
This endpoint retrieves a specific account.
Engines
Get engines
curl https://api.positionly.com/v2/engines/<google|yahoo|bing>.json
Response:
[
{
"id": 1,
"domain": "www.google.com.ar",
"provider": "Google",
"created_at": "2011-09-17T00:40:17+02:00",
"language_name": "español (Latinoamérica)",
"language_code": "es"
},
{
"id": 3,
"domain": "www.google.com.au",
"provider": "Google",
"created_at": "2011-09-17T00:40:17+02:00",
"language_name": "English",
"language_code": "en"
},
<...>
]
This endpoint retrieves engines.
Regions
Get engine regions
curl https://api.positionly.com/v2/engines/<engine_id>/regions.json
Response:
[
{
"id": 1,
"name": "Cordova,Alaska",
},
{
"id": 2,
"name": "Valley,Alabama",
},
<...>
]
Groups
Get all groups
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/groups.json
Response:
[
{
"id": 1,
"website_id": 1,
"name": "Example"
},
{
"id": 2,
"website_id": 1,
"name": "Other"
},
<...>
]
This endpoint retrieves all groups.
Get a specific group
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/groups/GROUP_ID.json
Response:
{
"id": 1,
"website_id": 1,
"name": "Example",
"website": {
"id": 11,
"account_id": 1,
"name": "https://example.com",
"title": "Example"
},
"keywords": []
}
This endpoint retrieves a specific group.
Create group
curl -X POST -d '{ "name": "Example", "keywords_ids": [1, 2] }'/group.json https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/groups.json
Response:
{
"status": "ok",
"group": {
"id": 1,
"website_id": 1,
"name": "Example"
}
}
This endpoint creates a group.
Parameters:
| Parameter | Description | Type |
|---|---|---|
name |
Group’s name | String, ex. "name": "Positionly" |
keywords_ids |
Group keywords ids | Array of integers, ex. "keywords_ids": [24, 25, 78] |
Delete group
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/groups/GROUP_ID.json
Response:
{
"status": "ok"
}
This endpoint deletes the group.
Get group positions
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID/groups/GROUP_ID/positions.json
Response:
{
"id": 1,
"website_id": 1,
"name": "Example",
"positions": {
"2013-01-24": 66.4,
"2013-01-25": 50,
"2013-01-26": 72.6,
"2013-01-27": 38.9,
"2013-01-28": 54,
"2013-01-29": 62.7,
"2013-01-30": 48
}
}
This endpoint retrieves group positions.
Keywords
Get all keywords
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/keywords.json
Response:
[
{
"id": 1,
"group_id": null,
"website_id": 1,
"name": "example",
"created_at": "2016-02-22T16:27:23.400Z"
},
{
"id": 2,
"group_id": null,
"website_id": 1,
"name": "example test",
"created_at": "2016-02-22T16:27:23.400Z"
},
<...>
]
This endpoint retrieves all keywords.
Get a specific keyword
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/keywords/KEYWORD_ID.json
Response:
{
"id": 1,
"group_id": null,
"website_id": 1,
"name": "example",
"website": {
"id": 11,
"account_id": 1,
"name": "https://positionly.com",
"title": "Example"
},
"group": null
}
This endpoint retrieves a specific keyword.
Create keyword
curl -X POST -d '{ "name": "example" }' https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/keywords.json
Response:
{
"status": "ok",
"keyword": {
"id": 1,
"group_id": null,
"website_id": 1,
"name": "example",
"website": {
"id": 11,
"account_id": 1,
"name": "https://example.com",
"title": "Example"
},
"groups": null
}
}
This endpoint creates a keyword.
Optional Parameters:
| Parameter | Description | Type |
|---|---|---|
groups |
Name of the groups | Array of string, ex. "groups": ["name", "name2", "name3"] |
Delete keyword
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/keywords/KEYWORD_ID.json
Response:
{
"status": "ok"
}
This endpoint deletes the keyword.
Get keyword positions
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID/keywords/KEYWORD_ID/positions.json?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD
Response
{
"id": 1,
"group_id": null,
"website_id": 1,
"name": "example",
"positions": {
"2013-01-24": 66,
"2013-01-25": 50,
"2013-01-26": 72,
"2013-01-27": 38,
"2013-01-28": 54,
"2013-01-29": 62,
"2013-01-30": 48
}
}
This endpoint retrieves keyword positions.
Optional 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 |
Get keyword positions for competitors
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID/keywords/KEYWORD_ID/positions/competitors.json?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD
Response
{
"id": 1,
"group_id": null,
"website_id": 1,
"name": "example",
"competitors": [
{
"id": 3,
"name": "https://example1.com",
"positions": {
"2013-01-24": 66,
"2013-01-25": 50,
"2013-01-26": 72,
"2013-01-27": 38,
"2013-01-28": 54,
"2013-01-29": 62,
"2013-01-30": 48
}
},
{
"id": 4,
"name": "https://example2.com",
"positions": {
"2013-01-24": 60,
"2013-01-25": 56,
"2013-01-26": 73,
"2013-01-27": 37,
"2013-01-28": 53,
"2013-01-29": 60,
"2013-01-30": 41
}
}
]
}
This endpoint retrieves keyword positions for every competitor of given website.
Optional 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 |
Notes
Get all notes
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/notes.json
Response:
[
{
"id": 1,
"owner_id": 1,
"website_id": 1,
"account_id": 1,
"bodytext": "Note",
"created_at": "2012-05-01T10:18:10+02:00"
},
{
"id": 2,
"owner_id": 1,
"website_id": 1,
"account_id": 1,
"bodytext": "Another note",
"created_at": "2012-05-01T10:18:21+02:00"
},
<...>
]
This endpoint retrieves all notes.
Get a specific note
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/notes/NOTE_ID.json
Response:
{
"id": 1,
"owner_id": 1,
"website_id": 1,
"account_id": 1,
"bodytext": "Note",
"created_at": "2012-05-01T10:18:10+02:00",
"website": {
"account_id": 1,
"id": 1,
"name": "https://example.com",
"title": "Example"
},
"keywords": [],
"engines": []
}
This endpoint retrieves a specific note.
Create note
curl -X POST -d '{ "bodytext": "Note" }' https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/notes.json
Response:
{
"status": "ok",
"note": {
"id": 1,
"owner_id": 1,
"website_id": 1,
"account_id": 1,
"bodytext": "Note",
"created_at": "2012-05-01T10:18:10+02:00",
"website": {
"account_id": 1,
"id": 1,
"name": "https://example.com",
"title": "Example"
},
"keywords": [],
"engines": []
}
}
This endpoint creates a note.
Delete note
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/notes/NOTE_ID.json
Response:
{
"status": "ok"
}
This endpoint deletes the note.
Users
Get user info
curl https://api.positionly.com/v2/user.json
Response:
{
"id": 1,
"name": "John Smith",
"email": "john@example.com",
"avatar": "/avatars/medium/missing.png"
}
This endpoint retreieves user information.
Website Engines
Get all website engines
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines.json
Response
[
{
"id": 1,
"website_id": 1,
"engine_provider": "Google",
"engine_name": "United States"
},
<...>
]
This endpoint retrieves all website engines.
Get a specific website engine
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID.json
Response:
{
"id": 1,
"website_id": 1,
"engine_provider": "Google",
"engine_name": "United States"
}
This endpoint retrieves a specific website engine.
Create website engine
curl -X POST -d '{ "engine_id": 1 }' https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines.json
Response:
{
"status": "ok",
"engine": {
"id": 1,
"website_id": 1,
"engine_provider": "Google",
"engine_name": "United States"
}
}
This endpoint creates a website engine.
Delete website engine
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID.json
Response:
{
"status": "ok"
}
This endpoint deletes the website engine.
Get keyword positions for website engine
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID/positions.json?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD
Response:
{
"id": 1,
"website_id": 1,
"engine_provider": "Google",
"engine_name": "United States",
"keywords": [
{
"id": 1,
"groups_id": [1, 2],
"name": "Example",
"positions": {
"2015-01-01": 1,
"2015-01-02": 2
}
}
]
}
This endpoint retrieves all keyword positions for website engine.
Optional 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 |
Website Phone Number
Get website phone number
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/phone_number.json
Response
[
{
"phone_numbers": ["123123123"],
"created_at": "2015-11-18T15:10:52.227Z",
"website": {
"id": 48,
"account_id": 50,
"name": "http://marquardt.biz",
"title": "Website no. 3"
}
}
]
This endpoint retrieves a website’s phone number.
Create website phone number
curl -X POST -d '{"phone_numbers": ["123123123", "12341234"]}' https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/phone_number.json
Response
[
{
"status": "ok",
"phone_number": {
"phone_numbers": ["123123123", "12341234"],
"created_at": "2015-11-18T15:15:45.264Z"
}
}
]
This endpoint creates a website’s phone numbers.
Please note that to separate multiple numbers you can put \n between them as well.
In that case shell command would look like this:
curl -X POST -d '{"phone_numbers": "123123123\n12341234"}' <...>
Delete a website phone number
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/phone_number.json
Response:
{
"status": "ok"
}
This endpoint deletes the website’s phone number.
Analytics
Get all analytics profiles
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/analytics.json
Response
[
{
"id": 1,
"name": "Profile_1",
"web_property_id": "UA-12345678-1"
},
<...>
]
This endpoint retrieves all Google Analytics profiles for given account.
Attach a profile to website
curl -X POST -d '{ "web_property_id": "UA-12345678-1" }' https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/analytics.json
Response
{
"status": "ok",
"analytics_profile": {
"id": 1,
"name": "Profile_1",
"web_property_id": "UA-12345678-1"
}
}
This endpoint connects a website with the given analytics profile.
Disconnect a profile from website
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/analytics.json
Response
{
"status": "ok"
}
This endpoint removes the analytics profile from the website.
Websites
Get all websites
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites.json
Response:
[
{
"id": 1,
"account_id": 1,
"name": "https://example.com",
"title": "Example",
"created_at": "2016-02-22T16:27:23.400Z"
},
<...>
]
This endpoint retrieves all websites.
Get a specific website
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID.json
Response:
{
"id": 1,
"account_id": 1,
"name": "https://example.com",
"title": "Example",
"engines": [
{
"id": 1,
"website_id": 1,
"engine_provider": "Google",
"engine_name": "United States"
},
<...>
],
"groups": [
{
"id": 1,
"website_id": 1,
"name": "Example"
},
<...>
],
"keywords": [
{
"id": 1,
"group_id": null,
"website_id": 1,
"name": "example"
},
{
"id": 2,
"group_id": null,
"website_id": 1,
"name": "example test"
},
<...>
]
}
This endpoint retrieves a specific website.
Create website
curl -X POST -d '{"name": "example.com"}' https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites.json
Response:
{
"status": "ok",
"website": {
"id": 1,
"account_id": 1,
"name": "https://example.com",
"title": "Example",
"engines": [
{
"id": 1,
"website_id": 1,
"engine_provider": "Google",
"engine_name": "Polska"
},
<...>
]
}
}
This endpoint creates a website.
Parameters:
| Parameter | Description | Type |
|---|---|---|
scheme |
Scheme type (optional) | String, ex. "scheme": "https://" |
title |
Website’s title (optional) | String, ex. "title": "Example" |
website_engines_attributes |
Website’s engines (optional) | Array of objects, ex. "website_engines_attributes": [ { "engine_id": 31 } ] |
Delete a website
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID.json
Response:
{
"status": "ok"
}
This endpoint deletes the website.
Get website positions
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID/positions.json
Response
{
"id": 11,
"account_id": 1,
"name": "https://positionly.com",
"title": "Example",
"positions": {
"2013-01-24": 66.4,
"2013-01-25": 50,
"2013-01-26": 72.6,
"2013-01-27": 38.9,
"2013-01-28": 54,
"2013-01-29": 62.7,
"2013-01-30": 48
}
}
This endpoint retrieves website positions (averages).
Competitors
Get all competitors
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/competitors.json
Response:
[
{
"account_id": 2,
"id": 15,
"name": "https://exaple_competitor.com",
"title": "exaple_competitor.com"
},
<...>
]
This endpoint retrieves all website competitors.
Get a specific competitor
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/competitors/COMPETITOR_ID.json
Response:
{
"id": 14,
"account_id": 2,
"name": "https://exaple_competitor.com",
"title": "exaple_competitor.com",
"engines": [
{
"engine_name": "Polska",
"engine_provider": "Google",
"id": 4,
"website_id": 3
},
<...>
],
"groups": [
{
"id": 3,
"name": "Example",
"website_id": 3
},
<...>
],
"keywords": [
{
"group_id": 2,
"id": 22,
"name": "test",
"website_id": 3
},
<...>
]
}
This endpoint retrieves a specific website competitor.
Create competitor
curl -X POST -d '{ "name": "positionly.com", "scheme": "http" }' https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/competitors.json
Response:
{
"status": "ok",
"competitor": {
"id": 1,
"account_id": 1,
"name": "https://positionly.com",
"title": "Xyz"
}
}
This endpoint creates a website competitor.
Delete competitor
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/competitors/COMPETITOR_ID.json
Response:
{
"status": "ok"
}
This endpoint deletes the competitor.
Get competitor positions for all your engines
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/competitors/COMPETITOR_ID/positions.json
Response:
{
"id": 14,
"account_id": 2,
"name": "https://exaple_competitor.com",
"title": "exaple_competitor.com",
"positions": {
"2014-10-09": 53.3,
"2014-10-10": 38.6,
"2014-10-11": 56.3,
"2014-10-12": 47.9,
<...>
}
}
This endpoint retrieves competitor positions for all engines.
Get competitor positions for engine
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID/competitors/COMPETITOR_ID/positions.json
Response:
{
"id": 14,
"account_id": 2,
"name": "https://exaple_competitor.com",
"title": "exaple_competitor.com",
"positions": {
"2014-10-09": 33.2,
"2014-10-10": 42.3,
"2014-10-11": 24.4,
"2014-10-12": 12.7,
<...>
}
}
This endpoint retrieves competitor positions for engine.
Reports
Get all manual reports
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/reports/manual.json
Response:
[
{
"id": 546,
"account_id": 1889,
"website_id": 1092,
"name": "Report 12",
"date_from": "2015-09-29",
"date_to": "2015-10-29",
"created_at": "2015-10-29T14:29:19.267Z",
"report_type": "simple",
"recurrence_interval_number": null,
"recurrence_interval_type": null,
"owner_id": 1,
"sort_order": "keyword_name",
"group_id": null,
"report_customization_id": null,
"parent_report_id": null
},
{
"id":545,
"account_id": 1889,
"website_id": 1092,
"name": "Report 11",
"date_from": "2015-09-29",
"date_to": "2015-10-29",
"created_at": "2015-10-29T14:29:19.258Z",
"report_type": "simple",
"recurrence_interval_number": null,
"recurrence_interval_type": null,
"owner_id": 1,
"sort_order": "keyword_name",
"group_id": null,
"report_customization_id": null,
"parent_report_id": null
},
<...>
]
This endpoint retrieves all manual reports.
Get all recurring reports
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/reports/recurring.json
Response
[
{
"id": 546,
"account_id": 1889,
"website_id": 1092,
"name": "Report 12",
"date_from": "2015-09-29",
"date_to": "2015-10-29",
"created_at": "2015-10-29T14:30:19.258Z",
"report_type": "simple",
"recurrence_interval_number": 1,
"recurrence_interval_type": "months",
"owner_id": 1,
"sort_order": "keyword_name",
"group_id": null,
"report_customization_id": null,
"parent_report_id": null
},
{
"id":545,
"account_id": 1889,
"website_id": 1092,
"name": "Report 11",
"date_from": "2015-09-29",
"date_to": "2015-10-29",
"created_at": "2015-10-29T14:29:19.258Z",
"report_type": "simple",
"recurrence_interval_number": 1,
"recurrence_interval_type": "months",
"owner_id": 1,
"sort_order": "keyword_name",
"group_id": null,
"report_customization_id": null,
"parent_report_id": null
},
<...>
]
This endpoint retrieves all recurring reports.
Get all auto-generated reports
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/reports/auto.json
Response
[
{
"id": 546,
"account_id": 1889,
"website_id": 1092,
"name": "Report 12",
"date_from": "2015-09-29",
"date_to": "2015-10-29",
"created_at": "2015-10-29T14:30:19.258Z",
"report_type": "simple",
"recurrence_interval_number": 1,
"recurrence_interval_type": "months",
"owner_id": 1,
"sort_order": "keyword_name",
"group_id": null,
"report_customization_id": null,
"parent_report_id": 540
},
<...>
]
This endpoint retrieves all auto-generated recurring reports.
Get a specific report
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/reports/REPORT_ID.json
Response:
{
"report":"Report 2",
"data":"\"Website\",\"Keyword\",\"Search Engine\",\"Average\",\"2015-09-30\",\"2015-10-30\"\n <...>"
}
This endpoint retrieves a specific report.
Create recurring report
curl -X POST -d '{ "website_id": 1092,"name": "Report 2","date_from": "2015-09-29","date_to": "2015-10-29","report_type": "simple","sort_order": "keyword_name","recurrence_interval_number": 2,"recurrence_interval_type": "months", "owner_id": 1, "new_account_contacts": ["email1@example.com", "email2@example.com"] }' https://api.positionly.com/v2/accounts/ACCOUNT_ID/reports/recurring.json
Response
{
"status": "ok",
"report": {
"id":545,
"account_id": 1889,
"website_id": 1092,
"name": "Report 11",
"date_from": "2015-09-29",
"date_to": "2015-10-29",
"created_at": "2015-10-29T14:29:19.258Z",
"report_type": "simple",
"recurrence_interval_number": 1,
"recurrence_interval_type": "months",
"owner_id": 1,
"sort_order": "keyword_name",
"group_id": null,
"report_customization_id": null
}
}
Parameters:
| Parameter | Description | Type |
|---|---|---|
name |
Name of the report | Text, ex. "name": "My API Report" |
date_from |
Report’s start date | Date in YYYY-MM-DD format, ex. "date_from": "2016-01-01" |
date_to |
Report’s end date | Date in YYYY-MM-DD format, ex. "date_to": "2016-02-01" |
report_type |
Type of the report | String, available options are: simple, advanced, links or traffic |
sort_order |
Report’s sort order | String, available options are: keyword_name, ranking_asc or ranking_desc |
recurrence_interval_type |
Recurrence period | String, available options are: days, weeks or months |
recurrence_interval_number |
Recurrence duration | Integer |
new_account_contacts |
Emails of people report will be sent to | Optional array of strings (email addresses) |
Create manual report
curl -X POST -d '{ "website_id": 1092,"name": "Report 2","date_from": "2015-09-29","date_to": "2015-10-29","report_type": "simple","sort_order": "keyword_name", "owner_id": 1, "new_account_contacts": ["email1@example.com", "email2@example.com"] }'
https://api.positionly.com/v2/accounts/ACCOUNT_ID/reports/manual.json
Response
{
"status": "ok",
"report": {
"id":545,
"account_id": 1889,
"website_id": 1092,
"name": "Report 11",
"date_from": "2015-09-29",
"date_to": "2015-10-29",
"created_at": "2015-10-29T14:29:19.258Z",
"report_type": "simple",
"recurrence_interval_number": null,
"recurrence_interval_type": null,
"owner_id": 1,
"sort_order": "keyword_name",
"group_id": null,
"report_customization_id": null
}
}
Set new_account_contacts option to send notification to listed emails.
This endpoint creates a manual report.
Delete report
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/reports/REPORT_ID.json
Response:
{
"status": "ok"
}
This endpoint deletes the report customization.
Report Customizations
Get all report customizations
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/reports/customizations.json
Response:
[
{
"id": 81,
"name": "Customization 3",
"footer": "Created by Customization",
"account_id": 3068,
"created_at": "2015-10-30T18:33:06.848Z",
"logo_file_name": "file.png",
"logo_content_type": "image/png",
"logo_file_size": 699,
"logo_updated_at": "2015-10-30T18:33:06.565Z”
},
{
"id": 81,
"name": "Customization 3",
"footer": "Created by Customization",
"account_id": 3068,
"created_at": "2015-10-30T18:33:06.848Z",
"logo_file_name": "file.png",
"logo_content_type": "image/png",
"logo_file_size": 699,
"logo_updated_at": "2015-10-30T18:33:06.565Z"
}
]
This endpoint retrieves all report customizations.
Create report customization
curl -v -H "Content-Type: multipart/form-data" -F "logo=@/Users/username/Desktop/file.jpg" -F "name=Customization 2" -F "footer=Created by Customization" https://api.positionly.com/v2/accounts/ACCOUNT_ID/reports/customizations.json
Response:
{
"status": "ok",
"report_customization": {
"id": 84,
"name": "Customization 2",
"footer": "Created by Customization",
"account_id": 3071,
"created_at": "2015-10-30T18:34:05.693Z",
"logo_file_name": "file.png",
"logo_content_type": "image/png",
"logo_file_size": 699,
"logo_updated_at": "2015-10-30T18:34:05.391Z"
}
}
This endpoint creates a report customization.
Delete report customization
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/reports/customizations/CUSTOMIZATION_ID.json
Response:
{
"status": "ok"
}
This endpoint deletes the report customization.
On Page Optimization
Get all OPOs
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/research/on-page-optimization.json
Response:
[
{
"id": 3,
"keywords": "keyword 199, keyword 200",
"created_at": "2015-11-10T09:50:45.733Z",
"checking":true
},
{
"id": 2,
"keywords": "keyword 195, keyword 196, keyword 198",
"created_at": "2015-11-09T14:13:31.192Z",
"checking":true
}
]
This endpoint retrieves all OPOs.
Get a specific OPO
curl https://api.positionly.com/v2/accounts/ACCOUNT_ID/research/on-page-optimization/ON_PAGE_OPTIMIZATION_ID.json
Response:
{
"id": 2,
"score": 68,
"issues": 4,
"major": {"value": 3, "total": 6},
"moderate": {"value": 0, "total": 7},
"minor": {"value": 1,"total": 2}
}
This endpoint retrieves a specific OPO.
Create OPO
curl -X POST -d'{ "url":"https://example.com"}'
https://api.positionly.com/v2/accounts/2/research/on-page-optimization.json
Response:
{
"status": "ok",
"opo": {
"id": 3,
"created_at": "2015-11-10T09:50:45.733Z",
"checking": true
}
}
This endpoint creates a OPO.
Optional parameters:
| Parameter | Type |
|---|---|
keywords - Keywords to check |
Text, ex. "keywords": "keyword_1, keyword_2" |
Delete OPO
curl -X DELETE https://api.positionly.com/v2/accounts/ACCOUNT_ID/research/on-page-optimization/ON_PAGE_OPTIMIZATION_ID.json
Response:
{
"status": "ok"
}
This endpoint deletes the OPO.