Charts Web Service API Guide (part of Project Picasso)

Quick Links

Endpoint | Data Providers | Examples

Overview

Picasso server generates charts conforming Oxford Economics standards using the latest data, directly drawn form various data sources.

Based on user’s preference, Picasso can either render a chart using the data provided by the user, or can communicate to Global Data Workstation APIs to get the latest data, as depicted in the figure below.

Charts Web Service Architecture

Endpoint

The API contains a single endpoint and the various data sources and chart customization options are defined in the request body. The endpoint returns a visual object in the requested format. A valid API key is required to get access to this service. To request an API key, please contact using the Helpdesk.

Endpoint: POST /api/chartRender

Method: POST

Request body structure

   
 {
  "headers":{
	"api-key":{{api_key}},
	"content-type": "application/json"
  },
  "body":{
	"format": {{format-type}},
	"chart": {
		"type": {{chart-type}},
		"width": number, 
		"height": number
		... //optional customization options wrt the chart type
	},
	"data": {
		"type": {{data-type}},
		... // the rest options depend on the selected type
	}
  }
}

The request body has three main objects, the prefered format of the response, the chart specifications and the data specifications.

Format

Format option defines the format of the API response. The supported format types are the following:

"svg": Picasso will respond with a chart in svg format.
"png": Picasso will respond with a chart in png format.
"base64": Picasso will respond with a base64 encoded version of the png.

Chart

Picasso can generate multiple chart types. Currently, the available values are:

"line": Picasso server will generate a line chart.
"column": Picasso server will generate a (simple or grouped) column chart.

Based on the selected chart type, the client application can also define a list of optional customization options that are defined for each chart type.

Data

Picasso can support multiple different data sources. Currently, the supported data types are the following:

"gdw1-saved-selection": Picasso API will communicate with Global Data Workstation API v1 to get the data, using user’s saved selection id.
"gdw1-custom-selection": Picasso API will communicate with Global Data Workstation API v1 to get the data, using user’s custom selection.
"gdw1-data": Picasso API does not need to communicate with the Global Data Workstation API, since the request body contains the data in a format of the Global Data Workstation API response. It is useful for client applications that already have the data from Global Data Workstation.
"custom-chart-data": Picasso API does not need to communicate with any other API or to re-shape the data. Data provided here should be in the correct format with respect to the requested chart type (line chart, column chart etc).

In each case described above, a different shape of the "data" object is required. The objects' layout and sample requests of each case are provided below.

Data types: request structure

1. Global Data Workstation Saved Selection

  
"data":{
    "type": "gdw1-saved-selection",
    "selectionId": {{gdw1-saved-selection-id}}
}

2. Global Data Workstation Custom Selection

  
"data":{
    "type": "gdw1-custom-selection",
    "selection": {...},
}

For detailed information on the selection format for the Global Data Workstation API, please visit Global Data Workstation API guide.

3. Global Data Workstation Data

  
"data":{
    "type": "gdw1-data",
    "values": [...]
}

4. Custom Chart Data

  
"data":{
    "type": "custom-chart-data",
    "values": {...} //The format of this object depends on the requested chart type.
}

In the Custom Chart Data type, the shape of the data request depends on the selected chart. Currently, line chart and column chart are supported and the data object layouts are the following:

(a) Custom Chart Data for the line chart

  
"data":{
    "type": "custom-chart-data",
    "values": {
        "title": string,
        "subtitle": string,
        "source": string,
        "forecastYear": "YYYY:Qi",
        "unitL": string,
        "scaleL": string,
        "measurementL": string,
        "unitR": string,
        "scaleR": string,
        "measurementR": string,
        "lineDataL": [
            {
                "legend": string,
                "values": [
                    {
                        "year": "YYYY:Qi",
                        "value": float
                    }     
                ]
            }
        ],
        "lineDataR": [
            {
                "legend": string,
                "values": [
                    {
                        "year": "YYYY:Qi",
                        "value": float
                    }
                ]
            }
        ]
    }
}

(b) Custom Chart Data for the column chart

  
"data": {
    "type": "custom-chart-data",
    "values": {
        "title": string,
        "subtitle": string,
        "source": string,
        "forecastYear": string,
        "unit": string,
        "scale": string,
        "measurement": string,
        "columnData": [
            {
                "groupName": string,
                "values": [
                    {
                        "value": float,
                        "category": string,
                        "selectionId": string,
                        "color": string,
                        "year": string,
                        "axisLabel": string,
                        "legend": string,
                        "locationCode": string,
                        "indicatorCode": string,
                        "measurement":string,
                        "unit": string,
                        "scale": string,
                        "source": string,
                        "historicalEnd": string
                    }
                ]
            }               
        ]
    }
}

Data types: example requests

A collection of sample requests that can be imported in Postman application is also available here .