Discover Positionly API

Positionly API allows you to access your account data programmatically

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=<your_username>&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=<your_username>&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"
}

Refresh token

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

or

curl 'https://api.positionly.com/v1/...?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.dev/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.dev/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.dev/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
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.dev/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.dev/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.dev/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.dev/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/v1/accounts/<account id>/websites.json
Parameters
* scheme
* name
* title
* website_engines_attributes": [
    { "engine_id": 31 }
]
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.dev/v1/accounts/<account id>/websites/<website id>.json
Parameters
{
    "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
    }
}