JSOCClient#

class sunpy.net.jsoc.JSOCClient[source]#

Bases: BaseClient

Provides access to the JSOC Data Export service.

It exposes a similar API to the VSO client, although the underlying model is more complex. The JSOC stages data before you can download it, so a JSOC query is a three stage process. First you query the JSOC for records, a table of these records is returned. Then you can request these records to be staged for download and then you can download them. The last two stages of this process are bundled together into the fetch() method, but they can be separated if you are performing a large or complex query.

Warning

JSOC requires you to register your email address before requesting data. See this on how to register.

Notes

The full list of Series is available through this site.

JSOC requires a validated email address, you can pass in your validated email address using the Notify attribute. You have to register your email address with JSOC beforehand here.

The backend of SunPy’s JSOC Client uses drms package. The tutorials can be found here. This can be used to build complex queries, by directly inputting the query string.

Examples

Example 1

Query JSOC for some HMI data at 45 second cadence:

>>> from sunpy.net import jsoc
>>> from sunpy.net import attrs as a
>>> client = jsoc.JSOCClient()
>>> response = client.search(a.Time('2014-01-01T00:00:00', '2014-01-01T00:10:00'),
...                          a.jsoc.Series('hmi.m_45s'), a.jsoc.Notify("sunpy@sunpy.org"))  

The response object holds the records that your query will return:

>>> print(response)   
         T_REC          TELESCOP  INSTRUME  WAVELNTH CAR_ROT
----------------------- -------- ---------- -------- -------
2014.01.01_00:00:45_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:01:30_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:02:15_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:03:00_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:03:45_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:04:30_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:05:15_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:06:00_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:06:45_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:07:30_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:08:15_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:09:00_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:09:45_TAI  SDO/HMI HMI_FRONT2   6173.0    2145
2014.01.01_00:10:30_TAI  SDO/HMI HMI_FRONT2   6173.0    2145

You can then make the request and download the data:

>>> res = client.fetch(response)   

This returns a Results instance which can be used to watch the progress of the download.

Note

A registered email address is not required if you only need to query for data, it is used only if you need to make an export request. For example,:

>>> client = jsoc.JSOCClient()  
>>> response = client.search(a.Time('2014-01-01T00:00:00', '2014-01-01T00:10:00'),
...                          a.jsoc.Series('hmi.m_45s'))  

The above is a successful query operation, and will return query responses as before.

But, this response object cannot be used to make an export request and will throw an error if done so:

>>> res = client.fetch(response)   

ValueError: Email address is invalid or not registered

Example 2

Query the JSOC for some AIA 171 data, and separate out the staging and the download steps:

>>> import astropy.units as u
>>> from sunpy.net import jsoc
>>> from sunpy.net import attrs as a
>>> client = jsoc.JSOCClient()  
>>> response = client.search(a.Time('2014/1/1T00:00:00', '2014/1/1T00:00:36'),
...                          a.jsoc.Series('aia.lev1_euv_12s'), a.jsoc.Segment('image'),
...                          a.Wavelength(171*u.AA), a.jsoc.Notify("sunpy@sunpy.org"))  

The response object holds the records that your query will return:

>>> print(response)  
       T_REC         TELESCOP INSTRUME WAVELNTH CAR_ROT
-------------------- -------- -------- -------- -------
2014-01-01T00:00:01Z  SDO/AIA    AIA_3      171    2145
2014-01-01T00:00:13Z  SDO/AIA    AIA_3      171    2145
2014-01-01T00:00:25Z  SDO/AIA    AIA_3      171    2145
2014-01-01T00:00:37Z  SDO/AIA    AIA_3      171    2145

You can then make the request:

>>> requests = client.request_data(response)  

This returns a list of all the ExportRequest objects for your query. You can get the ExportRequest ID

>>> requests.id  
'JSOC_20171205_372'

You can also check the status of the request, which will print out a status message and return you the status code, a code of 1 means it is not ready to download and a code of 0 means the request is staged and ready. A code of 6 means an error, which is commonly that the request has not had time to get into the queue:

>>> requests.status  
0

Once the status code is 0 you can download the data using the get_request method:

>>> res = client.get_request(requests)  

This returns a Results instance which can be used to watch the progress of the download:

>>> res.wait(progress=True)   

Attributes Summary

default_max_conn

info_url

This should return a string that is a URL to the data server or documentation on the data being served.

Methods Summary

create_parse_jsoc_values()

Makes a network call to the VSO API that returns what keywords they support.

fetch(jsoc_response[, path, progress, ...])

Make the request for the data in a JSOC response and wait for it to be staged and then download the data.

get_request(requests[, path, overwrite, ...])

Query JSOC to see if the request(s) is ready for download.

load_jsoc_values()

We take this list and register all the keywords as corresponding Attrs.

register_values()

This enables the client to register what kind of Attrs it can use directly.

request_data(jsoc_response[, method])

Request that JSOC stages the data for download.

search(*query, **kwargs)

Build a JSOC query and submit it to JSOC for processing.

Attributes Documentation

default_max_conn = 1#
info_url#

Methods Documentation

static create_parse_jsoc_values()[source]#

Makes a network call to the VSO API that returns what keywords they support. We take this list and register all the keywords as corresponding Attrs.

fetch(jsoc_response, path=None, progress=True, overwrite=False, downloader=None, wait=True, sleep=10, max_conn=1, **kwargs)[source]#

Make the request for the data in a JSOC response and wait for it to be staged and then download the data.

Note

Only complete searches can be downloaded from JSOC, this means that no slicing operations performed on the results object will affect the number of files downloaded.

Parameters:
  • jsoc_response (JSOCResponse object) – A response object

  • path (str) – Path to save data to, defaults to SunPy download dir

  • progress (bool, optional) – If True show a progress bar showing how many of the total files have been downloaded. If False, no progress bar will be shown.

  • overwrite (bool or str, optional) – Determine how to handle downloading if a file already exists with the same name. If False the file download will be skipped and the path returned to the existing file, if True the file will be downloaded and the existing file will be overwritten, if 'unique' the filename will be modified to be unique.

  • max_conn (int) – Maximum number of download connections.

  • downloader (parfive.Downloader, optional) – The download manager to use.

  • wait (bool, optional) – If False downloader.download() will not be called. Only has any effect if downloader is not None.

  • sleep (int) – The number of seconds to wait between calls to JSOC to check the status of the request.

Returns:

results (a parfive.Results instance) – A parfive.Results object.

get_request(requests, path=None, overwrite=False, progress=True, downloader=None, wait=True, max_conn=1, **kwargs)[source]#

Query JSOC to see if the request(s) is ready for download.

If the request is ready for download, it will then download it.

Parameters:
  • requests (ExportRequest, str, list) – ExportRequest objects or str request IDs or lists returned by request_data.

  • path (str) – Path to save data to, defaults to SunPy download dir.

  • progress (bool, optional) – If True show a progress bar showing how many of the total files have been downloaded. If False, no progress bar will be shown.

  • overwrite (bool or str, optional) – Determine how to handle downloading if a file already exists with the same name. If False the file download will be skipped and the path returned to the existing file, if True the file will be downloaded and the existing file will be overwritten, if 'unique' the filename will be modified to be unique.

  • downloader (parfive.Downloader, optional) – The download manager to use.

  • wait (bool, optional) – If False downloader.download() will not be called. Only has any effect if downloader is not None.

Returns:

res (parfive.Results) – A parfive.Results instance or None if no URLs to download

static load_jsoc_values()[source]#

We take this list and register all the keywords as corresponding Attrs.

Returns:

dict – The constructed Attrs dictionary ready to be passed into Attr registry.

classmethod register_values()[source]#

This enables the client to register what kind of Attrs it can use directly.

Returns:

dict – A dictionary with key values of Attrs and the values are a tuple of (“Attr Type”, “Name”, “Description”).

request_data(jsoc_response, method='url', **kwargs)[source]#

Request that JSOC stages the data for download. This method will not wait for the request to be staged.

Parameters:
  • jsoc_response (JSOCResponse object) – The results of a query

  • method ({"url", "url-tar", "url-quick"}) – Method for requesting JSOC data, can be ‘url-tar’, ‘url’ (the default) and ‘url-quick’ If ‘url-tar’ it will request JSOC to provide single .tar file which contains all data If ‘url’ it will request JSOC to provide all data as separate .fits files If ‘url-quick’ (only with protocol ‘as-is’) provide all data as separate files, but only if data is online.

Returns:

requests (ExportRequest object or) – a list of ExportRequest objects Request Id can be accessed by requests.id Request status can be accessed by requests.status

search(*query, **kwargs)[source]#

Build a JSOC query and submit it to JSOC for processing.

Takes a variable number of attrs as parameters, which are chained together using the AND (&) operator.

Complex queries to be easily formed using logical operators such as & and |, in the same way as the VSO client.

Parameters:

*query (a variable number of attrs) – as parameters, which are chained together using the AND (&) operator.

Returns:

response (JSOCResponse object) – A collection of records that the query returns.

Examples

Example 1

Request all AIA 304 image data between 2014-01-01T00:00 and 2014-01-01T01:00:

>>> import astropy.units as u
>>> from sunpy.net import jsoc
>>> from sunpy.net import attrs as a
>>> client = jsoc.JSOCClient()  
>>> response = client.search(a.Time('2017-09-06T12:00:00', '2017-09-06T12:02:00'),
...                          a.jsoc.Series('aia.lev1_euv_12s'), a.Wavelength(304*u.AA),
...                          a.jsoc.Segment('image'))  
>>> print(response)  
       T_REC         TELESCOP INSTRUME WAVELNTH CAR_ROT
-------------------- -------- -------- -------- -------
2017-09-06T11:59:59Z  SDO/AIA    AIA_4      304    2194
2017-09-06T12:00:11Z  SDO/AIA    AIA_4      304    2194
2017-09-06T12:00:23Z  SDO/AIA    AIA_4      304    2194
2017-09-06T12:00:35Z  SDO/AIA    AIA_4      304    2194
2017-09-06T12:00:47Z  SDO/AIA    AIA_4      304    2194
2017-09-06T12:00:59Z  SDO/AIA    AIA_4      304    2194
2017-09-06T12:01:11Z  SDO/AIA    AIA_4      304    2194
2017-09-06T12:01:23Z  SDO/AIA    AIA_4      304    2194
2017-09-06T12:01:35Z  SDO/AIA    AIA_4      304    2194
2017-09-06T12:01:47Z  SDO/AIA    AIA_4      304    2194
2017-09-06T12:01:59Z  SDO/AIA    AIA_4      304    2194

Example 2

Request keyword data of “hmi.v_45s” and show specific columns only:

>>> import astropy.units as u
>>> from sunpy.net import jsoc
>>> from sunpy.net import attrs as a
>>> client = jsoc.JSOCClient()  
>>> response = client.search(a.Time('2014-01-01T00:00:00', '2014-01-01T00:10:00'),
...                          a.jsoc.Series('hmi.v_45s'))  
>>> print(response.show('T_REC', 'WAVELNTH', 'CAR_ROT'))  
         T_REC          WAVELNTH CAR_ROT
----------------------- -------- -------
2014.01.01_00:00:45_TAI   6173.0    2145
2014.01.01_00:01:30_TAI   6173.0    2145
2014.01.01_00:02:15_TAI   6173.0    2145
2014.01.01_00:03:00_TAI   6173.0    2145
2014.01.01_00:03:45_TAI   6173.0    2145
2014.01.01_00:04:30_TAI   6173.0    2145
2014.01.01_00:05:15_TAI   6173.0    2145
2014.01.01_00:06:00_TAI   6173.0    2145
2014.01.01_00:06:45_TAI   6173.0    2145
2014.01.01_00:07:30_TAI   6173.0    2145
2014.01.01_00:08:15_TAI   6173.0    2145
2014.01.01_00:09:00_TAI   6173.0    2145
2014.01.01_00:09:45_TAI   6173.0    2145
2014.01.01_00:10:30_TAI   6173.0    2145

Example 3

Request data of aia.lev1_euv_12s on the basis of PrimeKeys other than T_REC:

>>> import astropy.units as u
>>> from sunpy.net import jsoc
>>> from sunpy.net import attrs as a
>>> client = jsoc.JSOCClient()  
>>> response = client.search(a.Time('2014-01-01T00:00:00', '2014-01-01T00:01:00'),
...                          a.jsoc.Series('aia.lev1_euv_12s'),
...                          a.jsoc.PrimeKey('WAVELNTH','171'))  
>>> print(response)  
       T_REC         TELESCOP INSTRUME WAVELNTH CAR_ROT
-------------------- -------- -------- -------- -------
2014-01-01T00:00:01Z  SDO/AIA    AIA_3      171    2145
2014-01-01T00:00:13Z  SDO/AIA    AIA_3      171    2145
2014-01-01T00:00:25Z  SDO/AIA    AIA_3      171    2145
2014-01-01T00:00:37Z  SDO/AIA    AIA_3      171    2145
2014-01-01T00:00:49Z  SDO/AIA    AIA_3      171    2145
2014-01-01T00:01:01Z  SDO/AIA    AIA_3      171    2145