API Specification

Zoho Analytics API uses HTTP as the underlying transport protocol. It is based on REST principles. The following are the basic points of how the REST APIs are structured:

  • Every table/report/dashboard in a Zoho Analytics workspace can be uniquely identified using a URL.
  • The operation to be performed on the table/report/dashboard can be specified using the parameters in the URL.
  • The additional payload required to perform the operation should also be specified as parameters in the URL.
  • Every request has a response whose format can be controlled using parameters in the request URL.

It is important to understand the API specification clearly before referring to the actual API methods.

Server URI

The following server URI are available for Zoho Analytics. Choose the server URI based on your data centre.

Data CentreZohoAnalytics_Server_URIZohoAccounts_Server_URIDeveloperConsole
US
(United States)		analyticsapi.zoho.comaccounts.zoho.comapi-console.zoho.com
EU
(Europe)		analyticsapi.zoho.euaccounts.zoho.euapi-console.zoho.eu
IN
(India)		analyticsapi.zoho.inaccounts.zoho.inapi-console.zoho.in
AU
(Australia)		analyticsapi.zoho.com.auaccounts.zoho.com.auapi-console.zoho.com.au
CN
(China)		analyticsapi.zoho.com.cnaccounts.zoho.com.cnapi-console.zoho.com.cn
JP
(Japan)		analyticsapi.zoho.jpaccounts.zoho.jpapi-console.zoho.jp

Request Format

All API requests should be placed as HTTPS requests. A request consists of the following components:

  • URI (Universal Resource Identifier. Also commonly known as URL)
  • Config to be passed in Query String
  • Authorization Using OAuth 2.0
  • Organization ID ( can be obtained using Get Organizations API )

URI

The URI of each resource can be obtained by accessing the API Root Endpoint.

Sample: https://<ZohoAnalytics_Server_URI>/restapi/v2/workspaces

CONFIG TO BE PASSED IN QUERY STRING

The following snippet shows the config that should be passed as query string with the URI defined above.

https://<end_point>?CONFIG={"workspaceName":"<workspace-name>"}

AUTHORIZATION USING OAUTH 2.0

Access token have to be passed in the header for authorization purpose in the format given below.

Authorization: Zoho-oauthtoken <access_token>

ORGANIZATION ID

{image}

Zoho Analytics Organization

For every organization in Zoho Analytics an unique ID (Organization ID) is present. The header “ZANALYTICS-ORGID“ with the 'Organization ID' should be sent with the API request to identify the organization.

ZANALYTICS-ORGID: <organization_id>

Using Get Organizations API the list of all accessible organizations can be obtained.

 

Note: In case of importing CSV or JSON files, multipart/form-data format should be used. (This is the default format used by HTML forms that contain file type fields used for uploading files.)

 

Sample Request

Copiedcurl  https://analyticsapi.zoho.com/restapi/v2/workspaces
  --data-urlencode 'CONFIG={
        "workspaceName":"<workspace-name>"
      }'
  -X 'POST'
  -H 'ZANALYTICS-ORGID: <org-id>'
  -H 'Authorization: Zoho-oauthtoken <access_token>'

Response Format

Zoho Analytics supports JSON response format for APIs. CSV, JSON, XML, PDF, HTML and Image response formats are supported only for Export API.

Note: See this link for response formats in case of errors on API execution.

Formats such as CSV, PDF can be specified only for EXPORT API. These formats don’t have any generic parseable header/footer. See this link for more details about these formats.

Sample Response

CopiedHTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
    "status": "success",
    "summary": "Create workspace",
    "data": {
        "workspaceId": "1767024000003145002"
    }
}

Error handling

API execution could result in Error conditions. In such cases, follow the below steps to identify an error condition and handle the same:

  • Check the HTTP response code. If it is 4xx or 5xx (eg., 400, 500, 401, etc.,), then it is an error.
  • In case of error, the error information would be sent in the response body.

Sample Error

CopiedHTTP/1.1 400 Bad Request
Content-Type:application/json;charset=UTF-8

{
    "status": "failure",
    "summary": "META_DBNAME_DUPLICATE",
    "data": {
        "errorCode": 7101,
        "errorMessage": "Workspace with the same name exists already. Provide an alternate name"
    }
}