Discover Positionly API (v1)

v1 API will be removed on 31st Dec 2015. v2 API will be released at the end of August 2015.

v2 API documentation can be found here

Get started

OAuth2

This information is provided to you by Positionly.

  • Client ID:
    de3be2752e8ae27a11cd96a6b0999b0f
  • Client secret:
    8d87664221c09681c3d3bc283a50bf73

Authorization

POST
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"
}
      

Refresh token

POST
  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"
}
      

Token usage example

  curl -H 'Authorization: ACCESS_TOKEN' 'https://api.positionly.com/v1/...'
      

or

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

Accounts

Accounts

GET
  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"
    },
    <...>
]
      

Account

GET
  curl https://api.positionly.com/v1/accounts/ACCOUNT_ID.json
      
Response
{
    "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": "http://example.com",
            "title": "Example"
        },
        <...>
    ]
}
      

Engines

Engines

GET
  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"
    },
    <...>
]
      

Groups

Groups

GET
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"
    },
    <...>
]
      

Group

GET
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": "http://example.com",
        "title": "Example"
    },
    "keywords": []
}
      

Create Group

POST
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": "http://example.com",
            "title": "Example"
        },
        "keywords": []
    }
}
      

Delete Group

DELETE
curl -X DELETE https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/groups/GROUP_ID.json
      
Response
{
    "status": "ok"
}
      

Group Positions

GET
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
    }
}
      

Keywords

Keywords

GET
  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"
    },
    <...>
]
      

Keyword

GET
  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": "http://positionly.com",
        "title": "Example"
    },
    "group": null
}
      

Create Keyword

POST
  curl -X POST -d @examples/keyword.json https://api.positionly.com/v1/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": "http://example.com",
            "title": "Example"
        },
        "group": null
    }
}
      

Delete Keyword

DELETE
  curl -X DELETE https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/keywords/KEYWORD_ID.json
      
Response
{
    "status": "ok"
}
      

Keyword Positions

GET
  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
      
Parameters
  • date_from (optional)
  • date_to (optional)
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
    }
}
      

Notes

Notes

GET
  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"
    },
    <...>
]
      

Note

GET
  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": "http://example.com",
        "title": "Example"
    },
    "keywords": [],
    "engines": []
}
      

Create Note

POST
curl -X POST -d @examples/group.json https://api.positionly.com/v1/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": "http://example.com",
            "title": "Example"
        },
        "keywords": [],
        "engines": []
    }
}
      

Delete Note

DELETE
  curl -X DELETE https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/notes/NOTE_ID.json
      
Response
{
    "status": "ok"
}
      

Users

User

GET
  curl https://api.positionly.com/v1/user.json
      
Response
{
    "id": 1,
    "name": "John Smith",
    "email": "john@example.com",
    "avatar": "/avatars/medium/missing.png"
}
      

Website Engines

Website Engines

GET
  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"
    },
    <...>
]
      

Website Engine

GET
  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"
}
      

Create Website Engine

POST
  curl -X POST -d @examples/engine.json  https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines.json
      
Response
{
    "status": "ok",
    "engine": {
        "id": 1,
        "website_id": 1,
        "engine_provider": "Google",
        "engine_name": "United States"
    }
}
      

Delete Website Engine

DELETE
curl -X DELETE https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID.json
      
Response
{
    "status": "ok"
}
      

Websites

Websites

GET
  curl https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites.json
      
Response
[
    {
        "id": 1,
        "account_id": 1,
        "name": "http://example.com",
        "title": "Example"
    },
    <...>
]
      

Website

GET
  curl https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID.json
      
Response
{
    "id": 1,
    "account_id": 1,
    "name": "http://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"
        },
        <...>
    ]
}
      

Create Website

POST
  curl -X POST -d @examples/website.json https://api.positionly.com/v1accounts/ACCOUNT_ID/websites.json
      
Parameters
  • scheme
  • name
  • title
Response
{
    "status": "ok",
    "website": {
        "id": 1,
        "account_id": 1,
        "name": "http://example.com",
        "title": "Example",
        "engines": [
            {
                "id": 1,
                "website_id": 1,
                "engine_provider": "Google",
                "engine_name": "Polska"
            },
            <...>
        ]
    }
}
      

Delete Website

DELETE
  curl -X DELETE https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID.json
      
Response
{
    "status": "ok"
}
      

Website Positions

GET
  curl https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/engines/ENGINE_ID/positions.json
      
Response
{
    "id": 11,
    "account_id": 1,
    "name": "http://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
    }
}
      

Competitors

Competitors

GET
  curl https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/competitors.json
      
Response
[
  {
      "account_id": 2,
      "id": 15,
      "name": "http://exaple_competitor.com",
      "title": "exaple_competitor.com"
  },
  <...>
]
      

Competitor

GET
  curl https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/competitors/COMPETITOR_ID.json
      
Response
{
  "id": 14,
  "account_id": 2,
  "name": "http://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
      },
      <...>
  ]
}
      

Competitor positions for all your engines

GET
  curl https://api.positionly.com/v1/accounts/ACCOUNT_ID/websites/WEBSITE_ID/competitors/COMPETITOR_ID/positions.json
      
Response
{
    "id": 14,
    "account_id": 2,
    "name": "http://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,
        <...>
    }
}
      

Competitor positions for engine

GET
  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": "http://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,
        <...>
    }
}