API Reference Guide

This guide to the Majestic API is designed to give an overview of our available data range, execution environments, authentication methods, connectors and our commands. Additional support is available through our support system.


Indexes

Majestic maintains two indexes of backlink data. Please see index update details at majestic.com for information on when these indexes were most recently updated.

Our Fresh Index shows all available backlink data we’ve collected in the past 90 days. Links in this index are either still live or have been lost within the past 90 days. The Fresh Index is updated several times daily.

The Historic Index contains all the backlink data we’ve collected in the past 5 years. This index is updated monthly, so newer links available in the Fresh Index may not yet be available in the Historic Index.

If no datasource is specified the default index is the Historic Index.

Use the datasource parameter to control which index is called. The datasource parameters to specify index are:

  1. datasource=historic historic
  2. datasource=fresh fresh


Use the Fresh Index for the most accurate flow metrics results.

Development Sandbox

We provide a development sandbox for testing purposes. Commands called in this environment will return data for only a specialized subset of our historic data and will not incur allowance costs.

To switch development environments at either protocol-level or through our connectors change the service endpoint, as demonstrated below.

  • Live service endpoint = http://api.majestic.com/api_command
  • Development service endpoint = http://developer.majestic.com/api_command

Authentication

Each request must be authenticated through a valid authentication protocol. Both our Full API and OpenApp protocols are supported by our connectors. More information on OpenApps is available here.

Examples of connector requests can be found at the connectors tab.

Allowances

The following allowances are available with plans of Platinum or above. Calling various commands may deduct from one or more of these allowances with each call made in live environments and are shown on each command’s reference page.

  • Analysis Units: This variable shows current number of analysis units currently available for use. This allowance will be used for most commands, with costs being available on each command page. This may also be listed as Max. analyzable backlinks or AnalysisResUnits.
  • Retrieval Units:This variable shows the number of retrieval units currently available for use. This allowance will be used for most commands, with costs being available on each command page. This may also be listed as RetrievalResUnits.
  • Index Item Units:This variable shows the number of index item units currently available for use. This allowance is used to call the GetIndexItemInfo command. This may also be listed as IndexItemInfoResUnits.


Using the API

The API works over the HTTP protocol, taking parameters from the request and returning a response in either XML or JSON. While you have the option to work on the protocol-level directly, we recommend exploring our suite of connectors.

Each command has its own set of parameters and characteristics. Some commands may support queuing, some may support batching or some commands may support both queuing and batching. Please refer to the specific command's documentation during integration.

All data is transmitted in UTF-8 format and may contain HMTL entities.

Response Types

We are now able to return API data in JSON format as well as XML format. XML is available through http://enterprise.majestic.com/api_command and JSON is available through http://enterprise.majestic.com/api/json.

XML

Return messages contain a set of message level parameters. These message level parameters may contain a set of datatables. It is possible for zero or more of these datatables to be returned with each message. Each returned datatable may contain its own parameters as well as zero or more rows of data.


Illustration of format of XML data returned from Majestic API.


Some commands can produce one and sometimes more data tables that consist of header with values and rows of data. Total number of available tables is shown Count parameter of DataTables element, and each subsequently embedded DataTable elements will have the following parameters: Name, RowsCount and Headers.

If rows of data are provided, the header information will be provided on a per table basis in order to identify columns. The ordering of columns is not guaranteed to be consistent between requests so positional data should only be used to map headers. Majestic reserves the right to vary the rows, columns and parameters or tables for any message returned at any time.

Datatable headers and row data are delimited by the Pipe character "|" (hexadecimal character: 0x7C). It is possible that some text cells may contain a "|" as part of the data, in which case the single pipe will be replaced with a double pipe - "||", so the data "Good Products | USA" is represented in the raw message data as "Good Products || USA".

Some cells may have empty values. In order to differentiate an empty cell from a quoted pipe, such empty cells are represented by a single space character (hexadecimal 0x20):
				Text| |more text
				     ^


The correct interpretation of the space within a cell is context sensitive, and is left to the client application to interpret.




Example of XML data returned through the Majestic API.

JSON

Return messages contain a set of message level parameters, and may optionally also contain a set of datatables. Zero or more datatables may be returned for each message. Each datatable may optionally contain its own parameters, and in addition, contains zero or more rows of data. Majestic reserves the right to vary the order of the returned data at any time.

Example of JSON data returned through the Majestic API.

For more information about access to the Majestic API suite, visit our Plans & Pricing page.