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.
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 .
1. Global Data Workstation Saved Selection
{
"format": "svg",
"chart": {
"type": "line",
"width": 623,
"height": 500
},
"data": {
"type": "gdw1-saved-selection",
"selectionId": "15f5a7e9-2e8d-4824-bca6-edfcdf32ca0b"
}
}
2. Global Data Workstation Custom Selection
{
"format": "svg",
"chart": {
"type": "line",
"width": 623,
"height": 500
},
"data": {
"type": "gdw1-custom-selection",
"selection": {
"Variables": [
{
"VariableCode": "CPI",
"ProductTypeCode": "WMC",
"MeasureCodes": [
"L"
]
}
],
"Regions": [
{
"DatabankCode": "WDMacro",
"RegionCode": "GBR"
},
{
"DatabankCode": "WDMacro",
"RegionCode": "IRL"
}
],
"StartYear": 2017,
"EndYear": 2025,
"Precision": 1,
"Frequency": "Annual"
}
}
}
3. Global Data Workstation Data
{
"format": "svg",
"chart": {
"type": "line",
"width": 623,
"height": 500
},
"data": {
"type": "gdw1-data",
"values": [
{
"DatabankCode": "WDMacro",
"ProductTypeCode": "WMC",
"LocationCode": "IRL",
"VariableCode": "CPI",
"MeasureCode": "L",
"Quarter": null,
"AnnualData": {
"2017": 100.6752,
"2018": 101.1677,
"2019": 102.4905,
"2020": 104.467,
"2021": 106.401,
"2022": 108.42,
"2023": 110.515,
"2024": 112.6798,
"2025": 114.91629999999999
},
"QuarterlyData": {},
"MonthlyData": {},
"Metadata": {
"Description": "Consumer price index",
"Location": "Ireland",
"DatabankName": null,
"ScaleFactor": "Dec-2016=100",
"AuthorEmail": "mbeck@oxfordeconomics.com",
"Author": "Martin Beck",
"AuthorTelephone": null,
"HistoricalEndYear": 2019,
"HistoricalEndQuarter": 2,
"ImposedEndYear": null,
"ImposedEndQuarter": null,
"BaseYearPrice": "",
"LastUpdate": "28 August 2019",
"SeasonallyAdjusted": true,
"SectorCoverage": "Whole Economy",
"BaseYearIndex": "Dec-2016",
"SourceDetails": "IENPC@IRELAND, seasonally adjusted",
"Units": "Index",
"Source": "Central Statistics Office Ireland\\Haver Analytics",
"AdditionalSourceDetails": "Ireland: Consumer Prices: All Items (NSA, Dec-16=100), seasonally adjusted",
"MeasureName": "Level",
"AnnualTypeCode": "A",
"PartnerName": "",
"IndicatorName": "Consumer price index",
"ScenarioName": "",
"CommodityName": "",
"MarketSectorName": "",
"IncomeBandName": "",
"HasQuarterly": false,
"CategoryDescription": "Prices and wages"
}
},
{
"DatabankCode": "WDMacro",
"ProductTypeCode": "WMC",
"LocationCode": "GBR",
"VariableCode": "CPI",
"MeasureCode": "L",
"Quarter": null,
"AnnualData": {
"2017": 103.3585,
"2018": 105.9167,
"2019": 107.91879999999999,
"2020": 109.91929999999999,
"2021": 111.77470000000001,
"2022": 113.856,
"2023": 116.03320000000001,
"2024": 118.302,
"2025": 120.6638
},
"QuarterlyData": {},
"MonthlyData": {},
"Metadata": {
"Description": "Consumer price index",
"Location": "United Kingdom",
"DatabankName": null,
"ScaleFactor": "2015=100",
"AuthorEmail": "agoodwin@oxfordeconomics.com",
"Author": "Andy Goodwin",
"AuthorTelephone": null,
"HistoricalEndYear": 2019,
"HistoricalEndQuarter": 2,
"ImposedEndYear": null,
"ImposedEndQuarter": null,
"BaseYearPrice": "",
"LastUpdate": "16 August 2019",
"SeasonallyAdjusted": false,
"SectorCoverage": "Whole Economy",
"BaseYearIndex": "2015",
"SourceDetails": "D7BT@UK",
"Units": "Index",
"Source": "Office for National Statistics\\Haver Analytics",
"AdditionalSourceDetails": "UK: Consumer Price Index: All Items (NSA, 2015=100) ",
"MeasureName": "Level",
"AnnualTypeCode": "A",
"PartnerName": "",
"IndicatorName": "Consumer price index",
"ScenarioName": "",
"CommodityName": "",
"MarketSectorName": "",
"IncomeBandName": "",
"HasQuarterly": false,
"CategoryDescription": "Prices and wages"
}
}
]
}
}
4. Custom Chart Data
(a) Line chart example
{
"format": "svg",
"chart": {
"type": "line",
"width": 623,
"height": 500
},
"data": {
"type": "custom-chart-data",
"values": {
"title": "ITA:CPI",
"subtitle": "vs GBR:CPI vs IRL:CPI",
"source": "Oxford Economics",
"forecastYear": "2019:Q2",
"unitL": "Index",
"scaleL": "2015=100",
"measurementL": "Level",
"unitR": "Index",
"scaleR": "Dec-2016=100",
"measurementR": "Level",
"lineDataL": [
{
"legend": "ITA:CPI (LHS)",
"values": [
{
"year": "2018:Q1",
"value": 101.6
},
{
"year": "2018:Q2",
"value": 102.2
},
{
"year": "2018:Q3",
"value": 102.8
},
{
"year": "2018:Q4",
"value": 102.4
},
{
"year": "2019:Q1",
"value": 102.6
},
{
"year": "2019:Q2",
"value": 103
},
{
"year": "2019:Q3",
"value": 103.5
},
{
"year": "2019:Q4",
"value": 104.6
},
{
"year": "2020:Q1",
"value": 103.5
},
{
"year": "2020:Q2",
"value": 104
},
{
"year": "2020:Q3",
"value": 104.4
},
{
"year": "2020:Q4",
"value": 104
},
{
"year": "2021:Q1",
"value": 104.532
},
{
"year": "2021:Q2",
"value": 105.285
},
{
"year": "2021:Q3",
"value": 105.8
},
{
"year": "2021:Q4",
"value": 105.7
}
]
},
{
"legend": "GBR:CPI (LHS)",
"values": [
{
"year": "2018:Q1",
"value": 104.767
},
{
"year": "2018:Q2",
"value": 105.667
},
{
"year": "2018:Q3",
"value": 106.3
},
{
"year": "2018:Q4",
"value": 106.9
},
{
"year": "2019:Q1",
"value": 106.7
},
{
"year": "2019:Q2",
"value": 107.8
},
{
"year": "2019:Q3",
"value": 108.291
},
{
"year": "2019:Q4",
"value": 108.884
},
{
"year": "2020:Q1",
"value": 108.95
},
{
"year": "2020:Q2",
"value": 109.91
},
{
"year": "2020:Q3",
"value": 110.097
},
{
"year": "2020:Q4",
"value": 110.72
},
{
"year": "2021:Q1",
"value": 110.69
},
{
"year": "2021:Q2",
"value": 111.744
},
{
"year": "2021:Q3",
"value": 111.985
},
{
"year": "2021:Q4",
"value": 112.672
}
]
}
],
"lineDataR": [
{
"legend": "IRL:CPI (RHS)",
"values": [
{
"year": "2018:Q1",
"value": 100.92
},
{
"year": "2018:Q2",
"value": 100.8
},
{
"year": "2018:Q3",
"value": 101.395
},
{
"year": "2018:Q4",
"value": 101.551
},
{
"year": "2019:Q1",
"value": 101.716
},
{
"year": "2019:Q2",
"value": 102.072
},
{
"year": "2019:Q3",
"value": 102.869
},
{
"year": "2019:Q4",
"value": 103.3
},
{
"year": "2020:Q1",
"value": 103.7
},
{
"year": "2020:Q2",
"value": 104.227
},
{
"year": "2020:Q3",
"value": 104.702
},
{
"year": "2020:Q4",
"value": 105.178
},
{
"year": "2021:Q1",
"value": 105.67
},
{
"year": "2021:Q2",
"value": 106.14
},
{
"year": "2021:Q3",
"value": 106.654
},
{
"year": "2021:Q4",
"value": 107.139
}
]
}
]
}
}
}
(b) Column chart example
{
"format": "svg",
"chart": {
"type": "column",
"width": 623,
"height": 500
},
"data": {
"type": "custom-chart-data",
"values": {
"title": "GBR-CPI",
"subtitle": "vs ITA-CPI",
"source": "Office for National Statistics\\Haver Analytics\\Istituto Nazionale di Statistica",
"forecastYear": "2019",
"unit": "%",
"scale": "",
"measurement": "% change y/y",
"columnData": [
{
"groupName": "2017",
"values": [
{
"value": 2.69,
"category": "GBR-CPI",
"selectionId": null,
"color": "#003469",
"year": "2017",
"axisLabel": null,
"legend": "GBR-CPI",
"locationCode": "GBR",
"indicatorCode": "CPI",
"measurement": "% change y/y",
"unit": "%",
"scale": "",
"source": "Office for National Statistics\\Haver Analytics",
"historicalEnd": "2019 Q2"
},
{
"value": 1.23,
"category": "ITA-CPI",
"selectionId": null,
"color": "#bd1b21",
"year": "2017",
"axisLabel": null,
"legend": "ITA-CPI",
"locationCode": "ITA",
"indicatorCode": "CPI",
"measurement": "% change y/y",
"unit": "%",
"scale": "",
"source": "Istituto Nazionale di Statistica\\Haver Analytics",
"historicalEnd": "2019 Q2"
}
]
},
{
"groupName": "2018",
"values": [
{
"value": 2.48,
"category": "GBR-CPI",
"selectionId": null,
"color": "#003469",
"year": "2018",
"axisLabel": null,
"legend": "GBR-CPI",
"locationCode": "GBR",
"indicatorCode": "CPI",
"measurement": "% change y/y",
"unit": "%",
"scale": "",
"source": "Office for National Statistics\\Haver Analytics",
"historicalEnd": "2019 Q2"
},
{
"value": 1.14,
"category": "ITA-CPI",
"selectionId": null,
"color": "#bd1b21",
"year": "2018",
"axisLabel": null,
"legend": "ITA-CPI",
"locationCode": "ITA",
"indicatorCode": "CPI",
"measurement": "% change y/y",
"unit": "%",
"scale": "",
"source": "Istituto Nazionale di Statistica\\Haver Analytics",
"historicalEnd": "2019 Q2"
}
]
}
]
}
}
}
Adelina Madhja is a Software Developer at Oxford Economics.
Arvindra Sehmi is Chief Information Officer and Director of IT at Oxford Economics.