NAV
shell
documentation

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

Refresh token

  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": "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.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 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

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.

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.

API v1

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

Refresh token

  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": "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/v1/...'

or

  curl https://api.positionly.com/v1/...?access_token=ACCESS_TOKEN

Accounts

Get all accounts

curl https://api.positionly.com/v1/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/v1/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/v1/engines/<google|yahoo|bing>.json

Response:

[
    {
        "id": 1,
        "domain": "www.google.com.ar",
        "provider": "Google",
        "language_name": "español (Latinoamérica)",
        "created_at": "2011-09-17T00:40:17+02:00"
    },
    {
        "id": 3,
        "domain": "www.google.com.au",
        "provider": "Google",
        "language_name": "English",
        "created_at": "2011-09-17T00:40:17+02:00"
    },
    <...>
]

This endpoint retrieves engines.

Groups

Get all groups

curl https://api.positionly.com/v1/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/v1/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 new group

curl -X POST -d @examples/group.json https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/groups.json

Response:

{
    "status": "ok",
    "group": {
        "id": 1,
        "website_id": 1,
        "name": "Example",
        "website": {
            "id": 11,
            "account_id": 1,
            "name": "https://example.com",
            "title": "Example"
        },
        "keywords": []
    }
}

This endpoint creates a group.

Parameter Type
name - Group’s name Text, ex. "name": "Positionly"
keywords_ids - Group keywords ids Integer, ex. "keywords_ids": [24, 25, 78]

Delete a group

curl -X DELETE https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/groups/GROUP_ID.json

Response:

{
    "status": "ok"
}

This endpoint deletes a specific group.

Get group positions

curl https://api.positionly.com/v1/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/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/keywords.json

Response:

[
    {
        "id": 1,
        "group_id": null,
        "website_id": 1,
        "name": "example"
    },
    {
        "id": 2,
        "group_id": null,
        "website_id": 1,
        "name": "example test"
    },
    <...>
]

This endpoint retrieves all keywords.

Get a specific keyword

curl https://api.positionly.com/v1/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 new 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 Type
groups - Group name Text, ex. "groups": ["name", "name2", "name3"]

This endpoint creates a keyword.

Delete a keyword

curl -X DELETE https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/keywords/KEYWORD_ID.json

Response:

{
    "status": "ok"
}

This endpoint deletes a keyword.

Get keyword positions

curl https://api.positionly.com/v1/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.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 keyword positions.

Optional parameters:

Parameter Type
date_from - Position start date curl <...>positions.json?date_from=YYYY-MM-DD
date_to - Position end date curl <...>&date_to=YYYY-MM-DD

Notes

Get all notes

curl https://api.positionly.com/v1/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/v1/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 new 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 a note

curl -X DELETE https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/notes/NOTE_ID.json

Response:

{
    "status": "ok"
}

This endpoint deletes a note.

Users

Get user info

 curl https://api.positionly.com/v1/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/v1/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/v1/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 new 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 a website engine

curl -X DELETE https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID.json

Response:

{
    "status": "ok"
}

Websites

Get all websites

curl https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites.json

Response:

[
    {
        "id": 1,
        "account_id": 1,
        "name": "https://example.com",
        "title": "Example"
    },
    <...>
]

This endpoint retrieves all websites.

Get a specific website

curl https://api.positionly.com/v1/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 new 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 Type
scheme - Scheme type (optional) Text, ex. "scheme": "https://"
title - Website’s title (optional) Text, ex. "title": "Example"
website_engines_attributes - Website’s engines (optional) Array, ex. "website_engines_attributes": [ { "engine_id": 31 } ]

This endpoint creates new website.

Delete a website

curl -X DELETE https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID.json

Response:

{
    "status": "ok"
}

This endpoint deletes a website.

Get website positions

curl https://api.positionly.com/v1/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.

Competitors

Get all competitors

curl https://api.positionly.com/v1/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/v1/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.

Get competitor positions for all your engines

curl https://api.positionly.com/v1/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/v1/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,
        <...>
    }
}