Copyscape Premium API

Technically speaking, the API (Application Programming Interface) allows your developers to write scripts on your server that query the Copyscape Premium service and receive results in XML or HTML format.

To use the API, please sign up for Copyscape Premium.

Using the API

The following sections provide the information you need to use the Copyscape Premium API:

Sample Code - Some examples which demonstrate how to use the API.

URL Search Request - Explains how to check for copies of a web page via the API.

Text Search Request - Explains how to check for copies of some text via the API.

XML Search Response - Describes XML responses that you receive from API search requests.

HTML Search Response - Describes HTML responses that you receive from API search requests.

URL Add to Private Index Request - Explains how to add the content from a URL to your private index.

Text Add to Private Index Request - Explains how to add some text to your private index.

Add to Private Index Response - Describes responses from API requests that add to your private index.

Delete from Private Index Request and Response - Explains how to delete content from your private index.

Check Balance Request and Response - Describes how to check your account balance.

Sample Code

URL Search Request

http://www.copyscape.com/api/
https://www.copyscape.com/api/

Parameters are specified on the URL (using ? and &) as follows:

API operation (o): Use csearch to search against the public Internet or psearch to search against your private index. You can also use cpsearch to search against both the Internet and your private index, for the cost of two searches.

Source URL (q): As per the HTTP specification, this must be urlencoded. For example, ? should be replaced by %3F and & replaced by %26. Most languages provide a built-in function for urlencoding - see examples in PHP, Java and ASP.

Full comparisons (c): Set to a value between 1 and 10 to request a full text-on-text comparison (with an exact count of matching words) between the query text and the top (one to ten) results found. Note that full comparisons may add a delay of a few seconds.

Response format (f): If omitted or set to xml, the API will respond in XML. If set to html, the API will respond in basic HTML.

Ignore sites (i): Subdomains are also omitted from the results. For example, if set to site1.com,site2.com then www.site1.com and blog.site2.com would also be ignored. Ignore sites listed in your user settings are always applied.

Spend limit (i): If this parameter is omitted, the limit per search set in your User Settings is applied.

Example test (x): If set to 1, the API will search the Internet for copies of this page and you will not be charged.

Text Search Request

http://www.copyscape.com/api/
https://www.copyscape.com/api/

The text to be searched and other parameters can be specified in one of two ways:

• Form Encoded. Provide all parameter values as form-urlencoded data within the HTTP POST payload. This is how web browsers submit forms over HTTP, and will usually be easiest. If your scripting language lets you set up an HTTP POST request with a list of parameter values, it will probably build this form-urlencoded payload automatically.


• Raw POST. Provide all parameters except the text to be searched (parameter t) on the URL (using urlencoding and ? and &, as if this was an HTTP GET). Provide the text itself in the raw HTTP POST payload data with no parameter name and no urlencoding. This method may be easier if you are building HTTP requests at a lower level, or using a command-line tool such as curl.

API operation (o): Use csearch to search against the public Internet or psearch to search against your private index. You can also use cpsearch to search against both the Internet and your private index, for the cost of two searches.

Text encoding (e): Use an IANA name, such as UTF-8 (Unicode), ISO-8859-1 (Latin-1) or WINDOWS-1251 (Cyrillic).

Text to be searched (t): If you are using the Raw POST method, as described above, the raw text should be supplied in the POST payload without a parameter name and without any urlencoding.

Full comparisons (c): Set to a value between 1 and 10 to request a full text-on-text comparison (with an exact count of matching words) between the query text and the top (one to ten) results found. Note that full comparisons may add a delay of a few seconds.

Response format (f): If omitted or set to xml, the API will respond in XML. If set to html, the API will respond in basic HTML.

Ignore sites (i): Subdomains are also omitted from the results. For example, if set to site1.com,site2.com then www.site1.com and blog.site2.com would also be ignored. Ignore sites listed in your user settings are always applied.

Spend limit (i): If this parameter is omitted, the limit per search set in your User Settings is applied.

Example test (x): If set to 1, the API will search the Internet for copies of the text on this page and you will not be charged.

XML Search Response

The <query> value may differ from the original URL you supplied if there was a frameset or redirection.

The <allwordsmatched>, <allpercentmatched> and <alltextmatched> values are based on full comparisons performed between the source text and the top (up to 10) results found. They summarize the portion of the source text that was matched in any of these full comparisons. They are present if the c parameter is 3 or more, and the search was not performed against both the Internet and your private index simultaneously.

The <allviewurl> value can be used to display the list of results in an iframe or window. If used, the contents of this page must be displayed in full, without modification. Please note that these links are temporary, and are valid for no longer than a few weeks, after which they expire.

If the search request succeeded, the <response> element also contains zero or more <result> subelements, each describing one result that was found, will the following subelements:

The <minwordsmatched> value is an approximate and relative measure of the amount of matching content found for each result. For an exact count of matching words in the top results, use the c API parameter to request full comparisons.

The <viewurl> value can be used to display the found page, with the matching content highlighted, in an iframe or window. If used, the contents of this page must be displayed in full, without modification.

If a full text-on-text comparison was performed for a result, its <result> subelement may also contain:

Please note that additional XML elements may be added in future, so your XML parser must safely ignore any elements or subelements which are not recognized.

HTML Search Response

If the search request succeeded, the title of the HTML page contains the URL queried (if appropriate) and the number of results found. The body of the page includes a series of paragraphs, one for each result, e.g.:

If the API request failed, the HTML response will contain some red text describing the error.

The HTML format may change in the future, so you should not rely on its structure. The HTML also contains less information than the XML format, and excludes full text-on-text comparisons. To show more information or ensure consistent formatting, please use the XML response format and build your own HTML.

URL Add to Private Index Request

To add the content from a URL to your private index, send an HTTP GET request to either of these URLs:

http://www.copyscape.com/api/
https://www.copyscape.com/api/

Parameters are specified on the URL (using ? and &) as follows:

Source URL (q) and Article ID (i): These parameters must be urlencoded. For example, ? should be replaced by %3F, & by %26 and space by + or %20. Most languages provide a built-in function for urlencoding - see examples in PHP, Java and ASP.

The title of the article in your private index is taken from the web page at the URL provided. The request returns a response confirming if the operation was successful.

Text Add to Private Index Request

To add some text to your private index, send an HTTP POST request to either of these URLs:

http://www.copyscape.com/api/
https://www.copyscape.com/api/

The text to be added and other parameters can be specified in one of two ways:

• Form Encoded. Provide all parameter values as form-urlencoded data within the HTTP POST payload. This is how web browsers submit forms over HTTP, and will usually be easiest. If your scripting language lets you set up an HTTP POST request with a list of parameter values, it will probably build this form-urlencoded payload automatically.


• Raw POST. Provide all parameters except the text to be added (parameter t) on the URL (using urlencoding and ? and &, as if this was an HTTP GET). Provide the text itself in the raw HTTP POST payload data with no parameter name and no urlencoding. This method may be easier if you are building HTTP requests at a lower level, or using a command-line tool such as curl.

Text encoding (e): Use an IANA name, such as UTF-8 (Unicode), ISO-8859-1 (Latin-1) or WINDOWS-1251 (Cyrillic).

Text to be added (t): If you are using the Raw POST method, as described above, the raw text should be supplied in the POST payload without a parameter name and without any urlencoding.

The request returns a response confirming if the operation was successful.

Add to Private Index Response

If the request to add to your private index succeeded, the <response> element contains the subelements <url> (for URL requests only), <words>, <handle>, <id> and <title>.

Please note that additional XML elements may be added in future, so your XML parser must safely ignore any elements or subelements which are not recognized.

For URL requests, the subelement <url> specifies the URL whose content was added. This may differ from the original URL you supplied if there was a frameset or redirection.

The subelement <words> specifies the number of words that were added.

The subelement <cost> specifies the cost in dollars of the operation performed.

The subelement <handle> provides a reference for the article created in the private index, which you may use to delete the article in the future. It consists of up to 32 ASCII characters.

The subelement <id> contains the article ID that you provided in the request (if any).

The subelement <title> contains the title of the article added to the private index. For URL requests, this is obtained from the title of the web page. For text requests, it contains the title that you provided (if any).

If the request to add to your private index failed, the <response> element contains a subelement <error> explaining the problem and, if appropriate, a subelement <query>.

For HTML responses, the API will return a message confirming whether the content was added successfully.

Delete from Private Index Request and Response

To delete an item of content from your private index, send an HTTP GET request to either of these URLs:

http://www.copyscape.com/api/
https://www.copyscape.com/api/

Parameters are specified on the URL (using ? and &) as follows:

For XML responses, a <response> element is returned. If the request succeeded, it contains:

If the delete request failed, the <response> element contains a subelement <error> explaining the problem.

For HTML responses, a textual description of the result of the request is returned as basic HTML.

There is no charge for deleting articles from your private index.

Check Balance Request and Response

http://www.copyscape.com/api/
https://www.copyscape.com/api/

Parameters are specified on the URL (using ? and &) as follows:

For XML responses, a <remaining> element is returned containing three subelements:

Note: For backwards compatibility, the response also contains a <total> field, but this no longer has a valid meaning. In the past, Copyscape Premium had a fixed price per search, so it was possible to know how many searches were available for a given balance. With per-word pricing, this is not possible.

For HTML responses, a textual description of your balance is returned as basic HTML.

Getting Assistance