JSOCClient

class sunpy.net.jsoc.JSOCClient[source] [edit on github]

Bases: object

This is a Client 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.jsoc.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.jsoc.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.jsoc.Time('2014/1/1T00:00:00', '2014/1/1T00:00:36'),
...                          a.jsoc.Series('aia.lev1_euv_12s'), a.jsoc.Segment('image'),
...                          a.jsoc.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)   

Methods Summary

check_request(requests)

Deprecated since version 0.9.

fetch(jsoc_response[, path, overwrite, …]) Make the request for the data in a JSOC response and wait for it to be staged and then download the data.
get(jsoc_response[, path, overwrite, …])

Deprecated since version 0.8.

get_request(requests[, path, overwrite, …]) Query JSOC to see if the request(s) is ready for download.
query(*query, **kwargs)

Deprecated since version 0.8.

request_data(jsoc_response, **kwargs) Request that JSOC stages the data for download.
search(*query, **kwargs) Build a JSOC query and submit it to JSOC for processing.
search_metadata(*query, **kwargs) Get the metadata of all the files obtained in a search query.

Methods Documentation

check_request(requests)[source] [edit on github]

Deprecated since version 0.9: The check_request function is deprecated and may be removed in a future version. Use drms.ExportRequest.status instead.

Check the status of a request and print out a message about it.

Parameters:requests (ExportRequest object or) – a list of ExportRequest objects, returned by request_data
Returns:status (int or list) – A status or list of status’ that were returned by JSOC.
fetch(jsoc_response, path=None, overwrite=False, progress=True, max_conn=5, downloader=None, sleep=10)[source] [edit on github]

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

Parameters:
  • jsoc_response (JSOCResponse object) – A response object
  • path (str) – Path to save data to, defaults to SunPy download dir
  • overwrite (bool) – Replace files with the same name if True
  • progress (bool) – Print progress info to terminal
  • max_conns (int) – Maximum number of download connections.
  • downloader (Downloader instance) – A Custom downloader to use
  • sleep (int) – The number of seconds to wait between calls to JSOC to check the status of the request.
Returns:

results (a Results instance) – A Results object

get(jsoc_response, path=None, overwrite=False, progress=True, max_conn=5, downloader=None, sleep=10)[source] [edit on github]

Deprecated since version 0.8: The get function is deprecated and may be removed in a future version. Use JSOCClient.fetch instead.

See fetch

get_request(requests, path=None, overwrite=False, progress=True, max_conn=5, downloader=None, results=None)[source] [edit on github]

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.
  • overwrite (bool) – Replace files with the same name if True.
  • progress (bool) – Print progress info to terminal.
  • max_conns (int) – Maximum number of download connections.
  • downloader (Downloader) – A Custom downloader to use
  • results (Results) – A Results manager to use.
Returns:

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

query(*query, **kwargs)[source] [edit on github]

Deprecated since version 0.8: The query function is deprecated and may be removed in a future version. Use JSOCClient.search instead.

See search

request_data(jsoc_response, **kwargs)[source] [edit on github]

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
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] [edit on github]

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.jsoc.Time('2017-09-06T12:00:00', '2017-09-06T12:02:00'),
...                          a.jsoc.Series('aia.lev1_euv_12s'), a.jsoc.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 for certain specific keywords 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.jsoc.Time('2014-01-01T00:00:00', '2014-01-01T00:10:00'),
...                          a.jsoc.Series('hmi.v_45s'),
...                          a.jsoc.Keys('T_REC, DATAMEAN, OBS_VR'))  
>>> print(response)  
             T_REC               DATAMEAN            OBS_VR
----------------------- ------------------ ------------------
2014.01.01_00:00:45_TAI        1906.518188        1911.202614
2014.01.01_00:01:30_TAI        1908.876221        1913.945512
2014.01.01_00:02:15_TAI          1911.7771 1916.6679989999998
2014.01.01_00:03:00_TAI        1913.422485 1919.3699239999999
2014.01.01_00:03:45_TAI        1916.500488        1922.050862
2014.01.01_00:04:30_TAI        1920.414795 1924.7110050000001
2014.01.01_00:05:15_TAI        1922.636963         1927.35015
2014.01.01_00:06:00_TAI 1924.6973879999998        1929.968523
2014.01.01_00:06:45_TAI        1927.758301 1932.5664510000001
2014.01.01_00:07:30_TAI        1929.646118         1935.14288
2014.01.01_00:08:15_TAI        1932.097046        1937.698521
2014.01.01_00:09:00_TAI 1935.7286379999998         1940.23353
2014.01.01_00:09:45_TAI        1937.754028        1942.747605
2014.01.01_00:10:30_TAI 1940.1462399999998        1945.241147

*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.jsoc.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
search_metadata(*query, **kwargs)[source] [edit on github]

Get the metadata of all the files obtained in a search query. Builds a jsoc query, similar to query method, and takes similar inputs.

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

Parameters:query (a variable number of attrs) – as parameters, which are chained together using the AND (&) operator.
Returns:res (DataFrame object) – A collection of metadata of all the files.

Example

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

Since, the function only performs a lookdata, and does not make a proper export request, attributes like Segment need not be passed:

>>> import astropy.units as u
>>> from sunpy.net import jsoc
>>> from sunpy.net import attrs as a
>>> client = jsoc.JSOCClient()  
>>> metadata = client.search_metadata(
...                         a.jsoc.Time('2014-01-01T00:00:00', '2014-01-01T00:01:00'),
...                         a.jsoc.Series('aia.lev1_euv_12s'), a.jsoc.Wavelength(304*u.AA))  
>>> print(metadata[['T_OBS', 'WAVELNTH']])  
                                                            T_OBS  WAVELNTH
aia.lev1_euv_12s[2014-01-01T00:00:01Z][304]  2014-01-01T00:00:08.57Z       304
aia.lev1_euv_12s[2014-01-01T00:00:13Z][304]  2014-01-01T00:00:20.58Z       304
aia.lev1_euv_12s[2014-01-01T00:00:25Z][304]  2014-01-01T00:00:32.57Z       304
aia.lev1_euv_12s[2014-01-01T00:00:37Z][304]  2014-01-01T00:00:44.58Z       304
aia.lev1_euv_12s[2014-01-01T00:00:49Z][304]  2014-01-01T00:00:56.57Z       304
aia.lev1_euv_12s[2014-01-01T00:01:01Z][304]  2014-01-01T00:01:08.59Z       304