JESS Web Service API

The JEplus Simulation Service (JESS) is an online server for running EnergyPlus and Radiance simulations on the ENSIMS' hybrid-cloud. Most of the jobs are executed on our on-premise cluster using the best computing nodes that are most suitable for the types of jobs. For large parametric simulations, additional cloud computing resources may be employed. In this way, JESS can deliver the best turn-around time for the users.

Key features

JESS offers some unique features to run E+ simulations online using ENSIMS' high-performance computing facilities.

Support both EnergyPlus simulations and jEPlus projects
Transparently support all E+ versions from V7.0 and above, with new versions added as soon as they are released
Unique run period-split method, delivering 5x acceleration on average while maintaining compatibility and accuracy in most use cases
Accessible using either a small client program for drop-in replacement of EnergyPlus.exe, or using the web API
Additional data access and viewer support through the web service

How to access

You will need an account on the ENSIMS web platform first, and request or link a separate JESS account to it. First, go to https://app.ensims.com and create an account. After log on, go to “My Account”, fill in your contact details (for invoicing) and then request a JESS account. The whole process takes only a few minutes.

Here is a video showing the process: https://youtu.be/LQmx2BiET70

API

Here is a summary of the available REST API functions.

User Authentication

Command	OP	URL	Cookie	Data	Return
Log on with credentials	POST	https://api.ensims.com/users/api/auth	none	User credential	Auth return
Check in with existing keys	POST	https://api.ensims.com/users/api/checkin	JWT	none	Auth return

JESS Operations

End point URL: https://api.ensims.com/jess_web/api

Group	Command	OP	URL	Cookie	Data	Return
General	Version info inquiry	GET	/info	none	none	Version info
JESS Account	Set/Update JESS Session	POST	/session	JWT	JESS credential	Response
	Verify JESS Session	GET	/session	JWT	none	Response
	Get JESS Account Info	GET	/account	JWT	none	Account Info Object
	Get Usage Info	GET	/usage	JWT	none	Usage Summary Object
	Get Jobs List	POST	/jobs	JWT	Filter	Job list report
Jobs	Upload and Run	POST	/job	JWT	Form data	Response
	Run uploaded files	POST	/job	JWT	Command	Response
	Rerun an existing job	POST	/job	JWT	Command	Response
	Cancel job	POST	/job/<job ID>	JWT	Command	Response
	Get Job Status	GET	/job/status/<job ID>	JWT	none	Job status object
	Get result directory	GET	/job/dir/<job ID>	JWT	none	Result directory object
	Download results	GET	/job/file/<job ID>[ext=???]	JWT	none	Zipped folder contents
	Download a result file/folder	GET	/job/file/<job ID>/<file name>	JWT	none	File stream
	Get a file in text mode	GET	/job/text/<job ID>/<file name>	JWT	none	File contents
Utilities	ESO - get indexes	GET	/eso/<job ID>/<case id>/<file name>	JWT	none	ESO variable tree object
	ESO - get variable	GET	/eso/var/<job ID>/<case id>/<file name>/<period>/<vars>	JWT	none	ESO variable data
	IDF - get tree	GET	/idf/<job ID>/<case id>/<file name>	JWT	none	IDF object tree
	IDF - get objects	GET	/idf/<job ID>/<case id>/<file name>/<type>/<obj id>	JWT	none	IDF object contents
	DXF - get 3D model ref	GET	/dxf/<job ID>/<case id>/<file name>	JWT	none	3D model reference
Other	IDD - Get tree	GET	/idd/<version>	none	none	IDD Type Tree
	IDD - Get tree (alt)	GET	/idd/alt/<version>	none	none	IDD Type Tree
	IDD - Get definition	GET	/idd/<version>/<type>	none	none	IDD Type Definition
	IDD - Get reference	GET	/idd/<version>/doc/<type>	none	none	Ref URL
	EPW - Get data (epw)	GET	/epw/<name>	none	none	File contents
	EPW - Get stats (json)	GET	/epw/json/<name>	none	none	Stats object

Accessing the API

The REST API is accessible with any HTTP client that allows you to assign data to the header and the body of each request. JEA uses only the GET and the POST methods. In general, when a data object is sent in the request's body, the POST method is used. To experiment and test the API commands, we recommend Postman. A Postman collection of transactions showing all the commands is available to download here.

Depending on the programming language you are using, there are numerous HTTP client to choose from. In this document, the examples of using curl and Requests for Python are provided in the descriptions of each transaction. Here is a quick example using the get version info command.

Browser

Since this command does not require authentication, you can try it in a web browser by typing in the following URL:

https://api.ensims.com/jess_web/api/info

If the service is accessible, you will receive a page containing the following text:

{
  "Title" : "JESS Web API",
  "Description" : "JESS online simulation services API provided by ENSIMS Ltd.",
  "Major" : 1,
  "Minor" : 0,
  "Revision" : 0,
  "Release" : "beta",
  "Update" : 1,
  "Notice" : "(C) 2020, Energy Simulation Solutions Ltd. All rights reserved."
}

curl

Send the same command using curl:

curl https://api.ensims.com/jess_web/api/info

The same text will be return with successful execution.

Requests

Make sure Requests is correctly installed in your Python environment, and run the following the lines:

>>> import requests
>>> r = requests.get('https://api.ensims.com/jess_web/api/info')
>>> r.json

Table of Contents