Workspace Metadata

Using the Workspace Metadata API, you can get the following meta information.

  • List of Reporting Workspaces in your account
  • List of Views and View Information in your Reporting Workspace
  • Different views available in Zoho Analytics
  • Datatypes available in Zoho Analytics

REQUEST URI

https://<ZohoAnalytics_Server_URI>/api/<OwnerEmail>

Get

oauthscope: ZohoAnalytics.metadata.read

COMMON PARAMETERS

ParameterPossible ValuesDescription
ZOHO_ACTIONDATABASEMETADATA This parameter specifies the action to be performed by the API request.
ZOHO_METADATA 
 

The supported values are:

  • ZOHO_CATALOG_LIST: To list the Zoho Analytics Workspaces for the specified user
  • ZOHO_CATALOG_INFO: To fetch information about the tables & reports (view) present in the given reporting Workspace in Zoho Analytics.
  • ZOHO_DATATYPES: To get the list of datatypes supported by Zoho Analytics
  • ZOHO_TABLETYPES: Various view types available in Zoho Analytics
Specifies the information to be fetched.
ZOHO_OUTPUT_FORMATXML/JSONThis parameter specifies the output format for the response.
ZOHO_ERROR_FORMATXML/JSONSpecifies the output format for the response in case an error occurs when trying to process the request.
ZOHO_API_VERSION1.0The API version of Zoho Analytics based on which the application(/service) has been written. This parameter allows the Zoho Analytics to handle applications based on the older versions.The current API version is 1.0

1. GETTING WORKSPACE (CATALOG) LIST

To list the Zoho Analytics Workspaces for the specified user

REQUEST URI

https://<ZohoAnalytics_Server_URI>/api/<OwnerEmail>

Get

COMMON PARAMETERS

Parameter NamePossible ValuesDescription
ZOHO_ACTIONDATABASEMETADATAThis parameter specifies the action to be performed by the API request.
ZOHO_METADATAZOHO_CATALOG_LISTTo list the Zoho Analytics workspaces for the specified user
ZOHO_OUTPUT_FORMATXML/JSONThis parameter specifies the output format for the response.
ZOHO_ERROR_FORMATXML/JSONSpecifies the output format for the response in case an error occurs when trying to process the request.
ZOHO_API_VERSION1.0The API version of Zoho Analytics based on which the application(/service) has been written. This parameter allows the Zoho Analytics to handle applications based on the older versions.The current API version is 1.0.

AUTHORIZATION

To make authenticated API request, append the access token in Authorization request header.

Header NameValueDescription
AuthorizationZoho-oauthtoken<space><access_token>The Access token provides a secure and temporary access to Zoho Analytics API's. Each access token will be valid only for an hour, and can be used only for the set of operations that is described in the scope.

2. GETTING TABLES AND REPORTS IN A WORKSPACE (CATALOG INFORMATION)

To list the Zoho Analytics Workspaces for the specified user

REQUEST URI

https://<ZohoAnalytics_Server_URI>/api/<OwnerEmail>/<WorkspaceName>

Get

COMMON PARAMETERS

Parameter NamePossible ValuesDescription
ZOHO_ACTIONDATABASEMETADATAThis parameter specifies the action to be performed by the API request.
ZOHO_METADATAZOHO_CATALOG_INFOTo fetch information about the tables & reports (view) present in the given reporting workspace in Zoho Analytics.
ZOHO_OUTPUT_FORMATXML/JSONThis parameter specifies the output format for the response.
ZOHO_ERROR_FORMATXML/JSONSpecifies the output format for the response in case an error occurs when trying to process the request.
ZOHO_API_VERSION1.0The API version of Zoho Analytics based on which the application(/service) has been written. This parameter allows the Zoho Analytics to handle applications based on the older versions.The current API version is 1.0.

AUTHORIZATION

To make authenticated API request, append the access token in Authorization request header.

Header NameValueDescription
AuthorizationZoho-oauthtoken<space><access_token>The Access token provides a secure and temporary access to Zoho Analytics API's. Each access token will be valid only for an hour, and can be used only for the set of operations that is described in the scope.

3. GETTING DATATYPE INFORMATION

The following table lists the common DATA TYPE numbers and its corresponding TYPE NAMES.

Data Type NumberType Name
12Plain Text / Multi Line Text / Email / URL
-7Yes / No Decision
8Percent / Currency / Decimal Number
-5Number / Auto Number / Positive Number
93Date

REQUEST URI

https://<ZohoAnalytics_Server_URI>/api/<OwnerEmail>

Get

COMMON PARAMETERS

Parameter NamePossible ValuesDescription
ZOHO_ACTIONDATABASEMETADATAThis parameter specifies the action to be performed by the API request.
ZOHO_METADATAZOHO_DATATYPESTo get the list of datatypes supported by Zoho Analytics
ZOHO_OUTPUT_FORMATXML/JSONThis parameter specifies the output format for the response.
ZOHO_ERROR_FORMATXML/JSONSpecifies the output format for the response in case an error occurs when trying to process the request.
ZOHO_API_VERSION1.0The API version of Zoho Analytics based on which the application(/service) has been written. This parameter allows the Zoho Analytics to handle applications based on the older versions.The current API version is 1.0.

AUTHORIZATION

To make authenticated API request, append the access token in Authorization request header.

Header NameValueDescription
AuthorizationZoho-oauthtoken<space><access_token>The Access token provides a secure and temporary access to Zoho Analytics API's. Each access token will be valid only for an hour, and can be used only for the set of operations that is described in the scope.

4. GETTING TABLE TYPES

The following table lists the common TABLETYPES.

Actual ViewTABLETYPE Value
TablesTABLE
Query TablesVIEW
Charts / Pivots / Tabular Views / Summary Views / DashboardsREPORT

REQUEST URI

https://<ZohoAnalytics_Server_URI>/api/<OwnerEmail>

Get

COMMON PARAMETERS

Parameter NamePossible ValuesDescription
ZOHO_ACTIONDATABASEMETADATAThis parameter specifies the action to be performed by the API request.
ZOHO_METADATAZOHO_TABLETYPESVarious view types available in Zoho Analytics
ZOHO_OUTPUT_FORMATXML/JSONThis parameter specifies the output format for the response.
ZOHO_ERROR_FORMATXML/JSONSpecifies the output format for the response in case an error occurs when trying to process the request.
ZOHO_API_VERSION1.0The API version of Zoho Analytics based on which the application(/service) has been written. This parameter allows the Zoho Analytics to handle applications based on the older versions.The current API version is 1.0.

AUTHORIZATION

To make authenticated API request, append the access token in Authorization request header.

Header NameValueDescription
AuthorizationZoho-oauthtoken<space><access_token>The Access token provides a secure and temporary access to Zoho Analytics API's. Each access token will be valid only for an hour, and can be used only for the set of operations that is described in the scope.

RESPONSE ATTRIBUTES

In this section, we have described the detailed explanation of the attribute / property we used in DATABASEMETADATA APIs.

Attribute/PropertyDescription
IS_DEFAULT/isDefaultIndicates whether a Zoho Analytics workspace is set as the default. Can be used to set default workspace for third party tools that loads Zoho Analytics Workspaces using JDBC Driver.
TABLE_CAT/tableCatZoho Analytics workspace name (ex: SalesDB)
COLUMN_NAME/columnNameName of the column in table type views (ex: Region)
LITERAL_PREFIXPrefix character used when literal values found (ex: '45’)
NULLABLEWill be true if the column can contain null value, false otherwise.
MAXSIZEMaximum size of the column (ex: 20)
TYPE_NAMEZoho Analytics name for the data type (ex: Positive Number)

Note:\N in XML response refer to the NULL value

GETTING METADATA USING JDBC DRIVER

In case you are using a Java application then Zoho Analytics offers a JDBC Driver and which can be used to fetch all the Zoho Analytics metadata information. Refer to the page JDBC Driver for details.

POSSIBLE ERROR CODES

7102 , 7103 , 8504 , 8506 , 8516 , 8533

Sample Request:

CurlCsharpGoJavaPHPPythonNode JSDeluge
Copiedcurl 
-d "ZOHO_ACTION=DATABASEMETADATA&ZOHO_OUTPUT_FORMAT=XML&ZOHO_ERROR_FORMAT=XML&ZOHO_API_VERSION=1.0&ZOHO_METADATA=ZOHO_CATALOG_LIST" 
-H "Authorization:Zoho-oauthtoken <access_token>" 
https://analyticsapi.zoho.com/api/EmailAddress
Copiedusing ZReports;

namespace Test
{
    CLIENT_ID = "************";
    CLIENT_SECRET = "************";
    REFRESH_TOKEN = "************";
    EMAIL = "Email Address";
    DBNAME = "Workspace Name";

    class Program
    {
        public IReportClient getClient()
        {
            IReportClient RepClient = new ReportClient(CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN);
            return RepClient;
        }

        public void getDatabaseMetaData(IReportClient RepClient)
        {
            string dbURI = RepClient.GetURI(EMAIL, DBNAME);
            string metaData = "ZOHO_CATALOG_INFO";
            string format = "XML";
            string result = RepClient.GetDatabaseMetaData(dbURI, metaData, format, null);
        }

        static void Main(string[] args)
        {
            Program obj = new Program();
            IReportClient rc = obj.getClient();
            obj.getDatabaseMetaData(rc);
        }
    }
}

Copiedpackage main

import (
	"fmt"
	"zoho/pkg/reportclient"
)

var (
	email        = "Email Address"
	clientid     = "************"
	clientsecret = "************"
	refreshtoken = "************"
)

func databasemetadata() {
	url := reportclient.GetUserUri(email)
	metadata := "ZOHO_CATALOG_LIST"
	data, err := reportclient.GetDatabaseMetadata(url, metadata)
	if err != nil {
		fmt.Println(err.ErrorMessage)
		fmt.Println(err.ErrorCode)
		fmt.Println(err.Action)
		fmt.Println(err.HttpStatusCode)
	} else {
		fmt.Println(data)
	}
}

func main() {
	reportclient.SetOAuthToken(clientid, clientsecret, refreshtoken)
	databasemetadata()
}

Copiedimport java.util.HashMap;
import java.util.Map;
import org.w3c.dom.Document;
import com.adventnet.zoho.client.report.*;

public class Sample {
    String clientId = "************";
    String clientSecret = "************";
    String refreshToken = "************";
    String email = "Email Address";
    Map<String, String> config = new HashMap<String, String>();
    private ReportClient rc = new ReportClient(clientId, clientSecret, refreshToken);

    public void metadata() throws Exception {
        String uri = rc.getURI(email);
        Document result = rc.getDatabaseMetaData(uri, "ZOHO_CATALOG_LIST", config);
    }

    public static void main(String[] args) throws Exception {
        Sample obj = new Sample();
        obj.metadata();
    }
}

Copied<?php
require 'ReportClient.php';

$EMAIL_ID = "Email Address";
$CLIENT_ID = "************";
$CLIENT_SECRET = "************";
$REFRESH_TOKEN = "************";
$report_client_request = new ReportClient($CLIENT_ID, $CLIENT_SECRET, $REFRESH_TOKEN);
$uri = $report_client_request->getUserURI($EMAIL_ID);
$metadata = "ZOHO_CATALOG_LIST";
$report_client_response = $report_client_request->getDatabaseMetadata($uri, $metadata);
?>

Copiedfrom __future__ import with_statement
from ReportClient import ReportClient
import sys

class Sample:
    LOGIN_EMAIL_ID = "Email Address"
    rc = None
    rc = ReportClient(REFRESH_TOKEN, CLIENT_ID, CLIENT_SECRET)

    def getdatabasemetadata(self, rc):
        uri = rc.getUserURI(self.LOGIN_EMAIL_ID)
        result = rc.getDatabaseMetadata(uri, "ZOHO_CATALOG_LIST")
        print(result)

    obj = Sample()
    obj.getdatabasemetadata(obj.rc)

Copiedvar nodelib = require('./ZAnalyticsClient');
var clientId = '************';
var clientSecret = '************';
var refreshtoken = '************';
var emailId = 'EmailAddress';
var metadataType = '';
nodelib.initialize(clientId, clientSecret, refreshtoken).then(() => {
    var params = {};
    var uripath = nodelib.getUri(emailId);
    if (metadataType == 'ZOHO_CATALOG_INFO') {
        var workspaceName = 'WorkspaceName';
        uripath = nodelib.getUri(emailId, workspaceName);
    }
    nodelib.getWorkspaceMetadata(metadataType, uripath, params).then((response) => {
        console.log(response);
    }).catch((error) => {
        console.log('Error : ' + error.message);
    });
}).catch((error) => {
    console.log('Authentication Error : ' + error);
});

Copiedemail = zoho.encryption.urlEncode("");
paramsMap = Map();
oauthParams = Map();
headers = Map();

// AUTHENTICATION PARAMS
oauthParams.put("client_id", "********");
oauthParams.put("client_secret", "********");
oauthParams.put("refresh_token", "********");
oauthParams.put("grant_type", "refresh_token");

tokenInfo = invokeurl[url:"https://accounts.zoho.com/oauth/v2/token"type:POSTparameters:oauthParams];
if (tokenInfo.containKey("access_token")) {
    accessToken = tokenInfo.get("access_token");
    headers.put("Authorization", "Zoho-oauthtoken ".concat(accessToken));
} else {
    info tokenInfo;
    return;
}

// COMMON PARAMS
paramsMap.put("ZOHO_ACTION", "DATABASEMETADATA");
paramsMap.put("ZOHO_OUTPUT_FORMAT", "JSON");
paramsMap.put("ZOHO_ERROR_FORMAT", "JSON");
paramsMap.put("ZOHO_API_VERSION", "1.0");

// ACTION SPECIFIC PARAMS
paramsMap.put("ZOHO_METADATA", "");
response = invokeurl[url: "https://analyticsapi.zoho.com/api/" + email
    type: POST parameters: paramsMap headers: headers];
info response;

Download SDK : C# | GO | JAVA | PHP | PYTHON | NodeJS

Sample Response:

XMLJson
Copied<responseURI="/api/EmailAddress"ACTION="ZOHO_CATALOG_LIST">
    <ZCATALOGS>
        <ZCATALOG IS_DEFAULT="1"TABLE_CAT="SalesDB"></ZCATALOG>
        <ZCATALOG IS_DEFAULT="0"TABLE_CAT="Super Store Sales"></ZCATALOG>
        <ZCATALOG IS_DEFAULT="0"TABLE_CAT="Project Manager"></ZCATALOG>
    </ZCATALOGS>
</response>
Copied{"response":
    {"uri": "\/api\/email",
        "action": "ZOHO_CATALOG_LIST",
        "result":
        [{"isDefault": true,
            "tableCat": "SalesDB"},
        {"isDefault": false,
            "tableCat": "Super Store Sales"},
        {"isDefault": false,
            "tableCat": "Project Manager"}]}}

Sample Response for Catalog Information:

XMLJson
Copied<responseURI="/api/EmailAddress/WorkspaceName"ACTION="ZOHO_CATALOG_INFO">
    <ZCATALOGTABLE_CAT="SalesDB">
    <ZVIEWREMARKS="\N"TABLE_NAME="SalesTable"TABLE_TYPE="TABLE">
    <ZCOLUMNS>
        <ZCOLUMNCOLUMN_NAME="REGION"PKCOLUMN_NAME="\N"NULLABLE="true"COLUMN_SIZE="100"PKTABLE_NAME="\N"DATA_TYPE="12"REMARKS="\N"TYPE_NAME="Plain Text"DECIMAL_DIGITS="-1"ORDINAL_POSITION="1"></ZCOLUMN>
        <ZCOLUMNCOLUMN_NAME="Order Date"PKCOLUMN_NAME="\N"NULLABLE="true"COLUMN_SIZE="19"PKTABLE_NAME="\N"DATA_TYPE="93"REMARKS="\N"TYPE_NAME="Date"DECIMAL_DIGITS="-1"ORDINAL_POSITION="6"></ZCOLUMN>
    </ZCOLUMNS>
    </ZVIEW>
    <ZVIEWREMARKS="\N"TABLE_NAME="Region"TABLE_TYPE="REPORT"></ZVIEW>
    <ZVIEWREMARKS="\N"TABLE_NAME="SalesTabular"TABLE_TYPE="REPORT">
    <ZVIEWREMARKS="\N"TABLE_NAME="SalesQuery"TABLE_TYPE="VIEW">
    <ZCOLUMNS>
        <ZCOLUMNCOLUMN_NAME="Market Type"PKCOLUMN_NAME="\N"NULLABLE="false"COLUMN_SIZE="100"PKTABLE_NAME="\N"DATA_TYPE="12"REMARKS="\N"TYPE_NAME="Plain Text"DECIMAL_DIGITS="-1"ORDINAL_POSITION="1"></ZCOLUMN>
        <ZCOLUMNCOLUMN_NAME="Order Date"PKCOLUMN_NAME="\N"NULLABLE="false"COLUMN_SIZE="19"PKTABLE_NAME="\N"DATA_TYPE="93"REMARKS="\N"TYPE_NAME="Date"DECIMAL_DIGITS="-1"ORDINAL_POSITION="2"></ZCOLUMN>
    </ZCOLUMNS>
    </ZVIEW>
    <ZVIEWREMARKS="\N"TABLE_NAME="SalesPivot"TABLE_TYPE="REPORT"></ZVIEW>
    <ZVIEWREMARKS="\N"TABLE_NAME="SalesSummary"TABLE_TYPE="REPORT"></ZVIEW>
</response>
Copied{"response":
    {"uri": "\/api\/email\/WorkspaceName",
        "action": "ZOHO_CATALOG_INFO",
        "result":
        {"views":
            [{"remarks": null,
                "tableName": "SalesTable",
                "tableType": "TABLE",
                "columns":
                [{"columnName": "REGION",
                    "pkcolumnName": null,
                    "nullable": true,
                    "columnSize": 100,
                    "pktableName": null,
                    "dataType": "12",
                    "remarks": null,
                    "typeName": "Plain Text",
                    "decimalDigits": -1,
                    "ordinalPosition": 1
                },
                {"columnName": "Order Date",
                    "pkcolumnName": null,
                    "nullable": true,
                    "columnSize": 19,
                    "pktableName": null,
                    "dataType": "93",
                    "remarks": null,
                    "typeName": "Date",
                    "decimalDigits": -1,
                    "ordinalPosition": 6
                }]},
            {"remarks": "Region wise chart for the year 2009",
                "tableName": "Region",
                "tableType": "REPORT",
                "columns":
                []},
            {"remarks": null,
                "tableName": "SalesTabular",
                "tableType": "REPORT",
                "columns":
                []},
            {"remarks": null,
                "tableName": "SalesQuery",
                "tableType": "VIEW",
                "columns":
                [{"columnName": "Market Type",
                    "pkcolumnName": null,
                    "nullable": false,
                    "columnSize": 100,
                    "pktableName": null,
                    "dataType": "12",
                    "remarks": null,
                    "typeName": "Plain Text",
                    "decimalDigits": -1,
                    "ordinalPosition": 1
                },
                {"columnName": "Order Date",
                    "pkcolumnName": null,
                    "nullable": false,
                    "columnSize": 19,
                    "pktableName": null,
                    "dataType": "93",
                    "remarks": null,
                    "typeName": "Date",
                    "decimalDigits": -1,
                    "ordinalPosition": 2
                }]},
            {"remarks": null,
                "tableName": "SalesPivot",
                "tableType": "REPORT",
                "columns":
                []},
            {"remarks": null,
                "tableName": "SalesSummary",
                "tableType": "REPORT",
                "columns":
                []}],
            "tableCat": "SalesDB"}}}

Sample Response for Datatype Information:

XMLJson
Copied<responseURI="/api/EmailAddress"ACTION="ZOHO_DATATYPES">
    <ZDATATYPES>
        <ZDATATYPELITERAL_PREFIX="&apos;"MAXSIZE="19"MAXIMUM_SCALE="\N"NULLABLE="1"TYPE_NAME="Positive Number"DATA_TYPE="-5"MINIMUM_SCALE="\N"SQL_DATA_TYPE="-5"FIXED_PREC_SCALE="false"LOCAL_TYPE_NAME="\N"AUTO_INCREMENT="false"SQL_DATETIME_SUB="0"PRECISION="-1"UNSIGNED_ATTRIBUTE="true"ID="5">
        </ZDATATYPE>
        <ZDATATYPELITERAL_PREFIX="&apos;"MAXSIZE="1"MAXIMUM_SCALE="\N"NULLABLE="1"TYPE_NAME="Yes/No Decision"DATA_TYPE="-7"MINIMUM_SCALE="\N"SQL_DATA_TYPE="-7"FIXED_PREC_SCALE="false"LOCAL_TYPE_NAME="\N"AUTO_INCREMENT="false"SQL_DATETIME_SUB="0"PRECISION="-1"UNSIGNED_ATTRIBUTE="false"ID="10">
        </ZDATATYPE>
    </ZDATATYPES>
</response>
Copied{"response":
    {"uri": "\/api\/email",
        "action": "ZOHO_DATATYPES",
        "result":
        [{"literalPrefix": "\'",
            "maxsize": 19,
            "maximumScale": null,
            "nullable": true,
            "dataType": -5,
            "minimumScale": null,
            "sqlDataType": -5,
            "fixedPrecScale": false,
            "localTypeName": null,
            "autoIncrement": false,
            "searchable": false,
            "literalSuffix": "\'",
            "caseSensitive": true,
            "numPrecRadix": "10",
            "typeName": "Positive Number",
            "createParams": "500",
            "sqlDatetimeSub": "0",
            "precision": -1,
            "unsignedAttribute": true,
            "id": "5"},
        {"literalPrefix": "\'",
            "maxsize": 1,
            "maximumScale": null,
            "nullable": true,
            "dataType": -7,
            "minimumScale": null,
            "sqlDataType": -7,
            "fixedPrecScale": false,
            "localTypeName": null,
            "autoIncrement": false,
            "searchable": false,
            "literalSuffix": "\'",
            "caseSensitive": true,
            "numPrecRadix": "10",
            "typeName": "Yes\/No Decision",
            "createParams": "500",
            "sqlDatetimeSub": "0",
            "precision": -1,
            "unsignedAttribute": false,
            "id": "10"}]}}

Sample Response for Table Types:

XMLJson
Copied<responseURI="/api/EmailAddress"ACTION="ZOHO_TABLETYPES">
    <ZVIEWTYPES >
        <ZVIEWTYPETYPE="TABLE"></ZVIEWTYPE>
        <ZVIEWTYPETYPE="VIEW"></ZVIEWTYPE>
        <ZVIEWTYPETYPE="REPORT"></ZVIEWTYPE>
    </ZVIEWTYPES>
</response> 
Copied{"response":
    {"uri": "\/api\/email",
        "action": "ZOHO_TABLETYPES",
        "result":
        ["TABLE",
            "VIEW",
            "REPORT"]}}