meta data for this page

JESS Web Service API

Version 1.0, ©2020 Energy Simulation Solutions Ltd


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

JESS Operations

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