MDL-Server user guide

MDL-Server user guide

All the functionality of Oxford Economics’ command line tool is now available as a web application and API. Once you’ve downloaded and started up the MDL-Server software, you will be able to import and export data from the model, run scenarios, and even render charts programmatically within your preferred analytics platform.

Setup and configuration

  1. Start by downloading the latest version of the MDL-Server software.
  2. Unzip the files to your host computer.
  3. From here, you have two options:
    a. MDL-Server.bat, a lightweight local server that shuts down when the user closes the application window
    b. MDL-Server_installer.msi, which installs the software to your computer and keeps it running in the background.
  4. If you're not sure which one to install or this is your first time trying out this software, we recommend the lightweight install. In either case, to complete installation, right click the file and select 'Run as administrator'.
  5. If you took the .bat file route, then your computer’s default web browser should automatically open to the web interface. This allows you to use all the API’s functionality in a straight-forward, sequential way.

    If you used the MSI installer or if your browser didn’t open to the web interface, you should still be able to access the web interface by going to http://localhost:9000. If you are accessing the server remotely or if you have configured the server to use a port other than 9000, you will have to adjust that URL accordingly.

A note on the resources directory

MDL-Server uses a set resources directory for finding bases to perform operations. It will attempt to use your OEF directory by default. However, this can be changed in a few ways. The easiest approach is to direct your browser to the MDL-Server (i.e. http://localhost:9000), and use the Set Resources Directory panel at the top of the page.

Endpoints

Each of the endpoints below returns a JSON object containing the requested data. Most require a Username and Password values in the header and each can take optional GET and POST payloads.

/Export

POST /api/export transfers selected data from a model base (.db file) to CSV, returning this data either in the HTTP response as text or as a URL from which you can download the spreadsheet containing the data.

  • The selection lines use the format Variable code, sector code, variable type ('V' for variable, 'R' for residual), measure code (see below), base name (or '.').
  • Several of these request and response objects have a MeasureCode field. This value describes how the annual data is represented. The available options are:
    • L - Level values
    • PY - Percentage difference year over year
    • DY - Difference year over year
    • P - Percentage difference quarter over quarter
    • D - Difference quarter over quarter
    • GR - Annualized growth rate
  • There are several formats available for exporting data. The latest list can be retrieved by performing a GET request against the /formats endpoint. Currently, these include:
    • Default - One row per series. Various metadata columns. Includes headers.
    • DefaultExtended - One row per series. A few extra metadata columns compared to Default. Includes headers.
    • Classic_v - Similar to Model software's one-column-per-series export.
    • Classic_h - Similar to Model software's Vars By Row export.
    • Skinny - Tall narrow format for import into cubes.
    • DatabankCompatible - One row per series, matching format of Global Data Workstation, Excel Data Workstation.
    • DatabankCompatibleStacked - One row per series and period, matching format of Global Data Workstation, Excel Data Workstation.
  • IncludeDownloadLink determines whether the output is returned as text in the response or as a link to download the exported file.
curl --request POST \
	--url 'https://localhost:9000/api/export' \
	--header 'Username: {{username}}' \
	--header 'Password: {{password}}' \
	--header 'content-type: application/json' \
	--data '{
	"Forecast": {
	"DatabaseFilePath": "may19.db",
	"ModelDirectory": "."
	},
	"Selection": [
	"GDP$,FRANCE,V,L,.",
	"GDP$,UK,V,L,."
	],
	"Format": "DatabankCompatible",
	"AnnualRollup": "True",
	"IncludeDownloadLink": "False"
	}'

/Import

POST /api/import transfers data supplied in the HTTP request to an Oxford Economics base (.db file).

curl --request POST \
	--url 'https://localhost:9000/api/import' \
	--header 'Username: {{username}}' \
	--header 'Password: {{password}}' \
	--header 'content-type: application/json' \
	--data '{
	"InputForecast": {
	"DatabaseFilePath": "may19.db",
	"ModelDirectory": "."
	},
	"OutputForecastPath": "may19_output.db",
	"ImportRows": [
	"Apr1.db,SAUDISR,C,V,L,198002,201204,0,40@01,1.00,2.00,3.00,4.00,5.00,6.00,7.00,8.00,9.00,10.00,11.00,12.00,13.00,14.00,15.00,16.00,17.00,18.00,19.00,20.00,21.00,22.00,23.00,24.00,25.00,26.00,27.00,28.00,29.00,30.00,31.00,32.00,33.00,34.00,35.00,36.00,37.00,38.00,39.00,40.00",
	"Apr1.db,UAEMOD,C,V,L,198001,201304,0,40@01,1.00,2.00,3.00,4.00,5.00,6.00,7.00,8.00,9.00,10.00,11.00,12.00,13.00,14.00,15.00,16.00,17.00,18.00,19.00,20.00,21.00,22.00,23.00,24.00,25.00,26.00,27.00,28.00,29.00,30.00,31.00,32.00,33.00,34.00,35.00,36.00,37.00,38.00,39.00,40.00"
	],
	"Vertical": "False",
	"OverwriteOutput": "True"
	}'

 

/QueueSolve

POST /api/queuesolve runs a model solve for a given base (.db file).

curl --request POST \
	--url 'https://localhost:9000/api/import' \
	--header 'Username: {{username}}' \
	--header 'Password: {{password}}' \
	--header 'content-type: application/json' \
	--data '{
	"InputForecast": {
	"DatabaseFilePath": "may19.db",
	"ModelDirectory": "."
	},
	"OutputForecastPath": "may19_output.db",
	"RunFileContents": [
	],
	"OverwriteOutput": "True"
	}'

/RenderChart

POST /api/renderchart takes a user-supplied data selection and uses Oxford Economics' online rendering software to generate a chart. The format of the request is nearly identical to that of the Export but for the ImageFormat field, which allows you to select the output file type (e.g. png, svg). For the Selection format, please see the section on the /Export endpoint.

curl --request POST \
	--url 'https://localhost:9000/api/renderchart' \
	--header 'Username: {{username}}' \
	--header 'Password: {{password}}' \
	--header 'content-type: application/json' \
	--data '{
	"Forecast": {
	"DatabaseFilePath": "may19.db",
	"ModelDirectory": "."
	},
	"FromYear": 2016,
	"ToYear": 2019,
	"Selection": [
	"GDP$,FRANCE,V,L,.",
	"GDP$,UK,V,L,."
	],
	"ImageFormat": "png",
	"AnnualRollup": "True",
	"IncludeDownloadLink": "False"
	}'

/ExportModelEntities

POST /api/exportmodelentities retrieves useful information about the series in a given model base (.db file). Available entities to be retrieved can be pulled via a GET request to the /entities endpoint and include:

curl --request POST \
	--url 'https://localhost:9000/api/exportmodelentities' \
	--header 'Username: {{username}}' \
	--header 'Password: {{password}}' \
	--header 'content-type: application/json' \
	--data '{
	"Forecast": {
	"DatabaseFilePath": "may19.db",
	"ModelDirectory": "."
	},
	"Entities": [
	"Fixes"
	]
	}'

/RunSequence

POST /api/runsequence takes a sequence of API commands as a single request and returns the resulting output as configured by the user.

curl --request POST \
	--url 'https://localhost:9000/api/runsequence' \
	--header 'Username: {{username}}' \
	--header 'Password: {{password}}' \
	--header 'content-type: application/json' \
	--data '{
	"Output": "ZipAll",
	"Requests": [
	{"Parameters":{"Forecast": {"DatabaseFilePath": "jul1.db", "ModelDirectory": "."}, "Selection": [ "GDP$,FRANCE,V,L,.", "GDP$,UK,V,L,." ], "Format": "DatabankCompatible", "AnnualRollup": "True"}, "RequestType": "Export"},
	{"Parameters":{"Forecast": { "DatabaseFilePath": "jul1.db", "ModelDirectory": "." }, "Selection": [ "GDP$,FRANCE,V,L,.", "GDP$,UK,V,L,." ], "ImageFormat": "png", "AnnualRollup": "True"}, "RequestType": "RenderChart"}
	]
	}'

Request header

HTTP requests to the API require three headers be set: Username, which should be set to the user's Oxford Economics website username, Password, the corresponding password, and content-type, which is typically just "application/json".

Example request, indicating proper HTTP headers:

curl --request GET --url \
	https://services.oxfordeconomics.com/api/export \
	--header 'Username: {{username}}' \
	--header 'Password: {{password}}' \
	--header 'content-type: application/json'
	...
  • Import rows take the form of Base name, sector, variable code, variable type, measure code, first data period (YYYYQQ), historical end period (YYYYQQ), C@PPY (where c is the count of datapoints and PPY is the periods per year 01 for annual, 04 for quarterly),data point,…
  • InputForecast is the .db file, which MDL-Server uses as the basis for the import. It will be copied and saved as OutputForecastPath with the new user-supplied data.
    • RunFileContents holds the contents of the user's run file separated by line, so that each line is a string in the list.
    • The file named by the InputForecast field remains unchanged. A new file is created with the name from the OutputForecastPath field that is a copy of InputForecast.
    • Expressions - Series equations, where they exist
    • Fixes - Fixes that have been applied by the user to exclude a range of data from a solve
    • Variables - The series present in the base
    • Coefficients - Coefficients set in the model
    • Each command takes the form of a RequestType, which is simply the name of the endpoint, e.g. RenderChart, Export, and a Parameter dictionary, which contains the payload for that command.
    • Output determines how the results of these commands are treated. The current available options are:
      • ZipAll - Combine all resulting files into a single archive
      • Final - Take only the result from the final command in your sequence