User Tools

You are here: start » docs » jess

Table of Contents

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

Since JESS is a paid service, you will need a separate account to use it. Make a request of creating a JESS account here: Request a JESS account. Free credits are available to new accounts.

API

Summary

The REST API calls are summarized in the table below.

Group Command OP Base URL Token Data Return
General Version info inquiry GET A /info none none Version info
Auth (Users API) Log on with credentials POST B /logon none User credential Auth return
Check in with existing keys POST B /checkin JWT none Auth return
JESS Account Set/Update JESS Session POST A /session JWT JESS credential Response
Verify JESS Session GET A /session JWT none Response
Get JESS Account Info GET A /account JWT none Account Info Object
Get Usage Info GET A /usage JWT none Usage Summary Object
Get Jobs List GET A /jobs JWT Filter Job list report
Jobs Upload and Run POST A /job JWT Form data Response
Run uploaded files POST A /job JWT Command Response
Rerun an existing job POST A /job JWT Command Response
Cancel job POST A /job/<job ID> JWT Command Response
Get Job Status GET A /job/status/<job ID> JWT none Job status object
Get result directory GET A /job/dir/<job ID> JWT none Result directory object
Download results GET A /job/file/<job ID> JWT none Zipped folder contents
Download a result file GET A /job/file/<job ID>/<file name> JWT none File contents
Utilities ESO - get indexes GET A /eso/<job ID>/<case id>/<file name> JWT none ESO variable tree object
ESO - get variable GET A /eso/var/<job ID>/<case id>/<file name>/<period>/<vars> JWT none ESO variable data
IDF - get tree GET A /idf/<job ID>/<case id>/<file name> JWT none IDF object tree
IDF - get objects GET A /idf/<job ID>/<case id>/<file name>/<type>/<obj id> JWT none IDF object contents
DXF - get 3D model ref GET A /dxf/<job ID>/<case id>/<file name> JWT none 3D model reference
Other IDD - Get tree GET A /idd/<version> none none IDD Type Tree
IDD - Get tree (alt) GET A /idd/alt/<version> none none IDD Type Tree
IDD - Get definition GET A /idd/<version>/<type> none none IDD Type Definition
IDD - Get reference GET A /idd/<version>/doc/<type> none none Ref URL
EPW - Get data (epw) GET A /epw/<name> none none File contents
EPW - Get stats (json) GET A /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

Page Tools

Site Tools