Home
Free Trial Sign In



  • Economic Impact
  • Research Techniques
  • Economic Impact Analysis
  • Cost-Benefit Analysis
  • Valuing Social Impact
  • Feasibility and Location Studies
  • Macro and Micro Forecasting
  • Data Analytics and Custom Models
  • Labour Market Analysis
  • Economic Development in EMs
  • State and Local Strategy
  • Scenario Analysis and Stress Testing
  •  
  • Economic Impact archive
  • By Topic
  • Browse Economic Impact by topic
  • By Industry
  • Browse Economic Impact by industry
  • Full archive
  • Publications in date order
  • Thought Leadership
  • Research Inputs
  • Global surveys
  • Executive interviews and case studies
  • Advisory panels and peer interchange
  • Social media research
  • Quantitative and economic analysis
  •  
  • Research Outputs
  • White papers, briefings, and think pieces
  • Charts, infographics, and dashboards
  • Analytical tools and models
  • Social and digital media
  • Microsites and presentations
  • Forward Thinking Blog
  • Click here for latest content
  •  
  • Thought Leadership Examples
  • By topic
  • Publications categorised by Topic
  • By Industry
  • Publications categorised by Industry
  • By Client
  • Publications categorised by Client
  • Full archive
  • Publications in date order

Techlabs

Helpful tips and guidance on

all the good stuff  that comes out of

Oxford Economics Technology Labs

  • Techlabs
  • Charts Web Service Api Guide Aka Project Picasso

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

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:

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


Chart

Picasso can generate multiple chart types. Currently, the available values are:
  1. "line": Picasso server will generate a line chart.
  2. "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:
  1. "gdw1-saved-selection": Picasso API will communicate with Global Data Workstation API v1 to get the data, using user’s saved selection id.
  2. "gdw1-custom-selection": Picasso API will communicate with Global Data Workstation API v1 to get the data, using user’s custom selection.
  3. "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.
  4. "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.

Power BI, Custom Charts, API, Global Data Workstation, Global Economic Model

Search our archive

Search our portfolio of public information
Go to archive
  • Oxford Economics
    • About us
    • Contact us
    • Economists and analysts
    • Careers
  • Products and services
    • Subscription services
    • Economic Impact
    • Thought Leadership
    • Forecasts and scenarios
    • Impact of policy change
  • Help and software
    • Help using our services
    • Software and downloads
    • Latest technology developments
  • Follow Us
    • LinkedIn
    • Twitter
    • Facebook
© Oxford Economics 2021 all rights reserved