Getting started with API

  • Request URL
  • Authorization
  • Interaction format - request
  • Interaction format - response
  • Limits
  • Data objects
  • Structure of API request URL

    An API request must be sent to https://api.topvisor.com by POST.
    A request URL must include the following data:

    <!-- https://api.topvisor.com/{version}/{format}/{operator of action}/{service name}[/{method name}] -->

    Example of API request URL:

    <!-- https://api.topvisor.com/{version}/{format}/{operator of action}/{service name}[/{method name}] --> https://api.topvisor.com/v2/json/get/user/profile/avatar

    Access and authorization

    To get started with the Topvisor API, get an API Key.
    Authorization request headers:

    User-Id: %USER_ID% Authorization: bearer %USER_API_KEY%

    Data format in request

    The data you send must be UTF-8 encoded.
    Data to be passed in two ways: JSON or form-data.

    Example of an API request URL that sets a data type:

    Content-type: application/json // JSON
    Content-type: ANY_OTHER // form-data (not recommended, e.g. x-www-form-urlencoded)

    Response format

    Response is encoded UTF-8 encoded.
    The only supported response format: JSON.

    {"result": /* result */,"nextOffset": /* number (can be absent) */,"total": /* number (can be absent) */,"errors":[/* array of errors (can be absent) */],"messages":[/* array of strings with notes (can be absent) */]}

    Find more about nextOffset and total on the Paginated selection page.
    Find more about errors on the Errors page.

    API limits

    • You can get up to 10 000 results per request
    • Up to 5 concurrent requests from a single IP
    • Up to 5 concurrent requests from a single User-Id

    If limits are exceeded, API returns an error with a 429 code.

    Data objects

    API allows to get, change and remove different data type objects. Each service is applicable to a certain data type. The list of all API services and the related objects is described in the Services section.

    For example, the Keyword service allows to manage the following objects: "Keywords", "Groups", and "Folders".

    Each data type has a unique list of properties. An example of a data type: Keywords