Linkdex API Documentation

From 31 January 2017 you must use HTTPS to access the Linkdex API

Release Notes

28 April 2017

• Added Tag Analysis API
  • POST https://api.linkdex.com/v1/rankings/[context]/taganalysis

    Form params:

    config

    mandatory

    domain

    mandatory

    tag

    optional

    reportName

    optional

• Share of Search API now available as POST for standard job request
  • POST https://api.linkdex.com/v1/rankings/[context]/shareofsearch

    Form params:

    config

    mandatory

    keyword

    optional

    tag

    optional

    reportName

    optional

• Added Market Winners API
  • POST https://api.linkdex.com/v1/rankings/[context]/marketwinners

    Form params:

    config

    mandatory

    tag

    optional

    reportName

    optional

OAuth access

The API uses "2-legged" OAuth v1.0a to provide authentication and authorisation services.

A Linkdex Account administrator can create an API user, which will be assigned an API key and a "secret". The key and secret should be used to sign any HTTP requests being submitted to the Linkdex API service using the HMAC-SHA1 algorithm.
The Java oauth-signpost library provides one simple method for doing this:

                    // create an HTTP request to a protected resource
                    URL url = new URL("https://api.example.com/protected")
                    HttpURLConnection request = (HttpURLConnection) url.openConnection();


                    // sign the request (consumer is a Signpost DefaultOAuthConsumer)
                    DefaultOAuthConsumer consumer = new DefaultOAuthConsumer("my_api_key", "my_api_secret");
                    consumer.sign(request);

                    // send the request
                    request.connect();
    		

The OAuth signing process also generates a timestamp and unique request id.
The Linkdex API will validate the signed request, including the timestamp and unique id, before allowing access to the requested resource.
An HTTP 401 Unauthorized response will be returned if access to the resource is not permitted.

Stateless requests with {path_context}

{path_context} contains contextual information to correctly identify resources being accessed.
The starting point for resource access is https://api.linkdex.com/v1/projects/list. This will return a collection of project descriptors available for the provided API key.

Resource access

Basic resource access

/<resource_type>/<context_path>/list

returns a list of resource descriptors containing a name and URI to access the resource

/<resource_type>/<context_path>/<id>

returns detailed information for an individual resource

Content Negotiation

The API supports retrieval of data in XML (application/xml) or JSON (application/json) format.
Requests to the API can include an Accept header to indicate the preferred response type.
The default response type is XML.

Asynchronous Export Generation

Some of the resources can have detailed exports generated with additional data. These will be generated asynchronously.

An export request will be of the form <path_to_resource>/<resource_id>/export_[format].

Once the export request has been submitted, an HTTP 202 Accepted response will be returned. The body of the response will contain a URL to monitor the progress of the export job. The URL will also be set in the Location header of the response.

The client can use this URL to retrieve the current status of the job; the status will be contained in the response body as plain text. Once the data are ready for retrieval, the response will contain a URL to allow download of the exported data.

Export data will be compressed using GZIP.