Replace YOUR_API_KEY in the instructions below by your own URL-encoded API key.
When logged in you can find your personal API key here.
Please be careful to keep the API key a secret when you use it.. all requests made through this key will be counted as a request on your behalf.
This is the syntax for a basic XML report with all data available, requiring just the API key and a urlencoded URL:
https://www.ranks.nl/x?url=http%3A//www.example.com/&api_key=YOUR_API_KEY
This would show just the top 10 highest wizard scores and the raw data for all keywords:
https://www.ranks.nl/x?mode=wiz,keys&fast=on&url=http%3A//www.example.com/&api_key=YOUR_API_KEY
Note the URL to analyze should also always be URL-encoded or unpredictable things may happen.
All variables mentioned below can be added to the basic API URLs.
##q
To return data from the Keyword Focus function, add a urlencoded keyword (search term) with the variable 'q'.
This will return an optimization score for the given URL and keyword combination, and the basic metrics
explaining the score.
##mode
With the variable "mode" you can control what to include in the XML if you do not want it all.
Seperate multiple mode values by comma's.
Mode Options are
'wiz' for a list of keywords with the highests scores on the page
'ph1' for single word keywords
'ph2' for 2 word phrases
'ph3' for 3 word phrases
'ph4' for 4 word phrases
'ph5' for 5 word phrases
'ph6' for 6 word phrases
'keys' for the combined 6 types of keywords (1,2,3,4,5 and 6 word phrases). Equals "ph1,ph2,ph3,ph4,ph5,ph6"
'elements' for the Elements part
'properties' for the Properties part
'foundonpage' for the FoundOnPage part
##max_wiz_count
possible values: 1- 1000
default: 10
##wizard rank only
If you are only interested in wizard ranks and scores and not in the other 'keys' data,
you can also set mode=wiz, and control the number of returned results with the max_wiz_count value.
This would show just the top 500 wizard scores:
https://www.ranks.nl/x?mode=wiz&fast=on&max_wiz_count=500&url=http%3A//www.example.com/&api_key=YOUR_API_KEY
########### OUTPUT FORMAT ###########
##fmt
possible values: xml | json | perl
default: xml
########### SPEED ###########
##fast
possible values: on|off
default: off
When 'fast' is 'on', things not needed to calculate the data per keyword are omitted.
fast=on is always recommended if you only need the 'wiz' and/or 'keys' modes.
This avoids checking for HTML errors in the document, checking readability,
and omits gathering detailed data about individual elements you might otherwise
see under the "Elements" section, such as data about lineage and the occurence
of links inside and outside of elements.
##msize
possible values: 1 - 500000
default: 500000
'msize' stands for maximum size. By default this is 500.000 bytes.
Larger pages take more time to process. Setting 'msize' to a value lower then 500000
will speed up the analysis of large pages, by only looking at the first 'msize' bytes
of the page. Setting 'msize' lower then 100000 bytes is likely to reduce the quality
to the report data somewhat. Setting it to 200000 is fine for most purposes though.
##time_out
possible values: 1 - 90
default: 30
The maximum time to wait for a single report, in seconds.
When generating large amounts of URLs, the Page Analyzer is bound to run into URLs
that respond very slowly. Generating a report for these URLs would take very long
or would ultimately fail if it takes longer then 90 seconds.
When the time_out value is reached, generating the report is aborted and a
timeout message is returned.
In XML
<RanksNLreport><ERROR>Timeout</ERROR></RanksNLreport>
In JSON
{"RanksNLreport":{"ERROR":"Timeout"}}
########### ADMINISTRATIVE FUNCTIONS ###########
##show_count
possible values: on|off
default: off
When 'show_count' is 'on', data about your approximate usage counts are added to the output of URL reports.
Note this slows down the response speed a little.
When 'show_count' is 'off', data about your approximate usage counts are not added to the output of URL reports.
##timer
possible values: on|off
default: off
When 'timer' is 'on', data about the time needed to generate a report is included in the output of URL reports.
When 'timer' is 'off', data about the time needed to generate a report is not included in the output of URL reports.
############################### WORD DEFINITIONS AND COUNTING ###############################
# The default settings should be OK for most situations, but feel free to experiment.
##smallword
possible values: 1-9
default: 2
A word should have at least this number of characters to be included in the reports as a single word
##no_single_quote_word_split
##alias: nsqws
possible values: on|off
default: on
When 'no_single_quote_word_split' is 'on', words in text strings are not split on single quote that connect words.
"You've got" would be considered two words
When 'no_single_quote_word_split' is 'off', words in text strings are split on every single quote.
"You've got" would be considered three words
##strip_underscores
##alias: stripu
possible values: on|off
default: on
When 'strip_underscores' is 'on', words in text strings are split on underscores.
"underscored_string" would be considered two words
When 'strip_underscores' is 'off', words in text strings are not split on underscores.
"underscored_string" would be considered one word
##strip_hyphens
##alias: striph
possible values: on|off
default: on
When 'strip_underscores' is 'on', words in text strings are split on hyphens.
"hyphened-string" would be considered two words
When 'strip_underscores' is 'off', words in text strings are not split on hyphens.
"hyphened-string" would be considered one word
############################### TEXT DEFINITIONS ###############################
##skipnoframes
possible values: on|off
default: off
When 'skipnoframes' is 'on', words found in NOFRAMES tags are not included in the total text and wordcounts extracted from the HTML
When 'skipnoframes' is 'off', words found in NOFRAMES tags are included in the total text and wordcounts extracted from the HTML
##skipoptionnames
possible values: on|off
default: off
When 'skipoptionnames' is 'on', words found in FORM OPTION tags are not included in the total text and wordcounts extracted from the HTML
When 'skipoptionnames' is 'off', words found in FORM OPTION tags are included in the total text and wordcounts extracted from the HTML
##skiptitleatt
possible values: on|off
default: on
When 'skiptitleatt' is 'on', words found in TITLE ATTRIBUTES are not included in the total text and wordcounts extracted from the HTML
When 'skiptitleatt' is 'off', words found in TITLE ATTRIBUTES are included in the total text and wordcounts extracted from the HTML
##skipalts
possible values: on|off
default: off
When 'skipalts' is 'on', words found in IMG ALT ATTRIBUTES are not included in the total text and wordcounts extracted from the HTML
When 'skipalts' is 'off', words found in IMG ALT ATTRIBUTES are included in the total text and wordcounts extracted from the HTML
##skipcomments
possible values: on|off
default: on
When 'skipcomments' is 'on', words found in COMMENT tags are not included in the total text and wordcounts extracted from the HTML
When 'skipcomments' is 'off', words found in COMMENT tags are included in the total text and wordcounts extracted from the HTML
##skipkeywords
possible values: on|off
default: off
When 'skipkeywords' is 'on', words found in META KEYWORDS tags are not included in the total text and wordcounts extracted from the HTML
When 'skipkeywords' is 'off', words found in META KEYWORDS tags are included in the total text and wordcounts extracted from the HTML
##skipdescription
possible values: on|off
default: off
When 'skipdescription' is 'on', words found in META DESCRIPTION tags are not included in the total text and wordcounts extracted from the HTML
When 'skipdescription' is 'off', words found in META DESCRIPTION tags are included in the total text and wordcounts extracted from the HTML
##skiptitle
possible values: on|off
default: off
When 'skiptitle' is 'on', words found in the TITLE tag are not included in the total text and wordcounts extracted from the HTML
When 'skiptitle' is 'off', words found in the TITLE tag are included in the total text and wordcounts extracted from the HTML
########### RETRIEVAL OPTIONS ###########
##accept_language_header
possible values: A valid Accept Language header
default: (no value)