Discover Positionly API

Get started

Beta Notice

  • Please note that this is a beta version of our API
  • Methods, keys, and structure might change before the API hits a stable branch

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,
        <...>
    }
}