WooRank (v1)

Download OpenAPI specification:Download

Welcome to the WooRank API documentation. Automate your website audit process through RESTful access to WooRank data using HTTP verbs GET, POST, PUT and DELETE. This documentation describes the resources that are available and how you use them.

authentication

All requests must be authenticated by including your secret API key in the request header X-API-KEY.

curl 'https://api.woorank.com/v1' -H "X-API-KEY: [API_KEY_HERE]"

The API key should be treated as a secret and handled with care. Do not publicly share your API key or use it in client-side code.

API Key Check

Use this endpoint to check that your API key is valid.

Responses

200

When the API key is valid.

401

When the API key is invalid.

get /
https://api.woorank.com/v1/

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error":
    {
    • "status": 401,
    • "message": "Unauthorized"
    }
}

versioning

When backwards-incompatible changes are made to the API, we release a new version. Some changes are considered non-breaking and API clients should be written so that they ignore these changes:

  • Additional properties added to responses
  • New API resources
  • New optional request parameters added to existing API methods

rate limiting

The WooRank API rate limit is set to 1200 calls per hour per API key (1200 requests/hour). PDF requests are limited to 5 calls per minute (5 requests/minute). For increasing and custom rate limiting please contact support@woorank.com

websites

The Website is the central entity of the WooRank API which references a real world website. A Website must be created before doing a Website Review. A Website can be promoted to be a Project, which allows extra features such as tracking keywords.

List all websites

List websites. The websites list uses cursor-based pagination via the cursor parameter. If a list response has a cursor value this means that there are more results to be fetched by providing that cursor value in another request.

query Parameters
project
boolean
Default: false

If true, websites that are projects are returned. By default, websites that are not projects are returned.

cursor
string

Retrieve websites after this cursor.

limit
integer
Default: 10

Max number of items to be returned. A value between 1 and 100.

Responses

200
get /websites
https://api.woorank.com/v1/websites

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "cursor": "123456789",
  • "data":
    [
    • {
      }
    ]
}

Create a website

Create a new Website for a URL.

Request Body schema: application/json
url
required
string

A full URL for the Website.

project
boolean
Default: false

If true, indicates that the Website should be a Project.

Responses

200
400

When the url can not be resolved.

403

When the maximum number of projects have been reached.

409

When a Website for this url already exists.

post /websites
https://api.woorank.com/v1/websites

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "url": "string",
  • "project": false
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    • "id": "bbc.com",
    • "isProject": true
    }
}

Retrieve a website

Retrieves the details of a Website.

path Parameters
id
required
string

The Website id.

Responses

200
404

When Website not found.

get /websites/{id}
https://api.woorank.com/v1/websites/{id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    • "id": "bbc.com",
    • "isProject": true
    }
}

Update a website

Updates details of a Website.

path Parameters
id
required
string

The Website id.

Request Body schema: application/json
project
boolean

Indicates if Website should be a Project or not

Responses

200
put /websites/{id}
https://api.woorank.com/v1/websites/{id}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "project": true
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    • "id": "bbc.com",
    • "isProject": true
    }
}

Delete a website

Delete a Website

path Parameters
id
required
string

The Website id.

Responses

200

When Website was successfully deleted.

404

When Website not found.

delete /websites/{id}
https://api.woorank.com/v1/websites/{id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "deleted": true
}

keywords

Track your site’s performance in Google search results for specified keywords. In order to manage keywords, your Website must be a Project. If your Website is not a Project, it needs to be promoted to one (see section Update a Website).

Delete keywords

Delete keywords.

path Parameters
id
required
string

The website id.

Request Body schema: application/json
keywords
required
Array of objects

The keywords to be added.

Responses

200

When keywords were successfully deleted

delete /websites/{id}/serp/keywords
https://api.woorank.com/v1/websites/{id}/serp/keywords

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "keywords":
    [
    • {
      }
    ]
}

Create keywords

Add keywords to be tracked.

path Parameters
id
required
string

The website id.

Request Body schema: application/json
keywords
required
Array of strings

The keywords to be added.

country
required
string (serp_country)
Enum: "ae" "ai" "am" "ar" "as" "at" "au" "az" "ba" "bd" "be" "bg" "bh" "bn" "bo" "br" "ca" "cd" "ch" "ci" "cl" "cn" "co" "cr" "cu" "cy" "cz" "de" "dj" "dk" "do" "ec" "ee" "eg" "es" "et" "fi" "fr" "ge" "gh" "gi" "gm" "gp" "gr" "gt" "hk" "hn" "hr" "ht" "hu" "id" "ie" "il" "in" "is" "it" "je" "jm" "jo" "jp" "ke" "kh" "kr" "kz" "li" "lk" "lt" "lu" "lv" "ly" "ma" "md" "mn" "mt" "mu" "mx" "my" "na" "nc" "ng" "ni" "nl" "no" "nu" "nz" "om" "pa" "pe" "ph" "pk" "pl" "pr" "pt" "py" "qa" "ro" "rs" "ru" "rw" "sa" "se" "sg" "si" "sk" "sm" "sn" "sv" "th" "to" "tr" "tt" "tw" "ua" "ug" "uk" "us" "uy" "uz" "vc" "ve" "vn" "yu" "za" "zm"
language
string (serp_language)
Enum: "default" "en" "af" "ar" "hy" "be" "bg" "ca" "zh-CN" "zh-TW" "hr" "cs" "da" "nl" "eo" "et" "tl" "fi" "fr" "de" "el" "he" "hi" "hu" "is" "id" "it" "ja" "ko" "lv" "lt" "no" "fa" "pl" "pt" "ro" "ru" "sr" "sk" "sl" "es" "sw" "sv" "th" "tr" "uk" "vi" "ach" "ak" "am" "az" "ban" "bem" "bn" "bs" "ceb" "ee" "eu" "fo" "fy" "ga" "gaa" "gl" "gu" "ha" "ht" "ig" "ka" "kg" "kk" "km" "kn" "ky" "lg" "ln" "lo" "loz" "lua" "mg" "mi" "mk" "ml" "mn" "mr" "ms" "mt" "my" "ne" "nso" "ny" "nyn" "om" "pa" "ps" "qu" "rm" "rn" "rw" "sd" "si" "sn" "so" "sq" "st" "ta" "te" "tg" "ti" "tk" "tn" "to" "tum" "ur" "uz" "wo" "xh" "yo" "zu"

Responses

200

When keywords were successfully added.

post /websites/{id}/serp/keywords
https://api.woorank.com/v1/websites/{id}/serp/keywords

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "keywords":
    [
    • "string"
    ],
  • "country": "ae",
  • "language": "default"
}

Retrieve keywords data

Get latest ranking data of the keywords of your website. Must be called once after adding new keywords to start collecting ranking data for them.

path Parameters
id
required
string

The website id.

query Parameters
country
string

Country of the keywords.

language
string

Language of the keywords. Providing the value 'default' will target only keywords with 'default' language. If this parameter is not sent, all keywords regardless of language are targeted.

urls
string

Competitor urls. Should be a comma separated list of URI encoded strings.

order-field
string

Specify which field to order the results by. Possible values are 'keyword', 'volume' or a url. When the order-field is a url, the results are ordered by keyword rank for that url.

order-direction
string

Specify which direction to order the results. Possible values are DESC or ASC.

keyword-match
string

Include only the keywords containing this string value. The filter is not case sensitive.

keyword-tag-names
string

Include only the keywords that has a tag included in this list. Should be a comma separated list of URI encoded strings.

Responses

200

A list of keywords with latest ranking results for their urls.

get /websites/{id}/serp/keywords-data
https://api.woorank.com/v1/websites/{id}/serp/keywords-data

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

reviews

A Website Review is an audit of a website’s technical, on-page and off-page SEO. A Website Review is given a WooRank Score, a dynamic grade on a 100-point scale rating SEO effectiveness.

Here is a typical scenario of API requests to get Website Review data. If a Website does not yet exist, create it first:

curl 'https://api.woorank.com/v1/websites' -H "X-API-KEY: [API_KEY_HERE]" -H "Content-Type: application/json" -d '{"url":"http://bbc.com"}'

Start the website review job (provide optional webhook to know when it is done):

curl 'https://api.woorank.com/v1/websites/bbc.com/review/job' -H "X-API-KEY: [API_KEY_HERE]" -H "Content-Type: application/json" -d '{"webhook":"http://mysite.com/webhooks"}'

Poll the following url to fetch the review data:

curl 'https://api.woorank.com/v1/websites/bbc.com/review' -H "X-API-KEY: [API_KEY_HERE]"

List all reviews

List reviews. The reviews list uses cursor-based pagination via the cursor parameter. If a list response has a cursor value this means that there are more results to be fetched by providing that cursor value in another request.

query Parameters
cursor
string

Retrieve reviews after this cursor.

limit
integer
Default: 10

Max number of items to be returned. A value between 1 and 100.

Responses

200
get /reviews
https://api.woorank.com/v1/reviews

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "cursor": "46320"
}

Retrieve review

Get detailed review data including criteria.

path Parameters
id
required
string

The website id.

query Parameters
criteria
string

The requested review criteria. Should be a comma separated list of URI encoded strings.

Responses

200
get /websites/{id}/review
https://api.woorank.com/v1/websites/{id}/review

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    • "url": "woorank.com",
    • "score": 90.3,
    • "updatedAt": "2018-11-19T13:04:56.876Z",
    • "criteria":
      {