Space Weather Data Share
Space Weather Data Share

Space Weather Data Share


How to use the API

The Space Weather Data Share Web API is based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint.

Making authorized requests to the Space Weather Data Share platform requires that you are granted permission to access data.

We had developed a complete package to download files from Space Weather Data Share API. You can see and download it from GitHub .

  • personObtaining Authorization arrow_drop_down
    You need use the method POST to request the /climaespacial/SpaceWeatherDataShare/api/auth/login/ endpoint.
    
    POST http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/auth/login/
    
                
    Headers

    The header of this POST request must contain the following parameter:

    
    Content-type: application/json
    
    
    Body raw

    You can login with your username or e-mail in 'username' JSON key.

        
    {
        "username": "your username or your e-mail",
        "password": "your-password"
    }
        
    
    Requests examples
    cURL
    
    curl -X POST -H "Content-Type: application/json" \
    -d '{"username": "your-username or e-mail", "password": "your password"}' \
    http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/auth/login/
    
                
    Python
    
    import urllib.parse
    import urllib.request
    import json
    
    values = {
          "username": "your username or e-mail",
          "password": "your password"
      }
    
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    request = urllib.request.Request('http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/auth/login/', data)
    
    
    response_body = urllib.request.urlopen(request).read()
    with urllib.request.urlopen(request) as response:
        response = json.loads(response.read().decode('utf-8'))
        token = response['token']
        print(token)
    
    
                
    Response

    On success, the response from the Space Weather Data Share Accounts service has the status code 200 OK in the response header, and the following JSON data in the response body

                    
    {
        "token": "eyJ0eXAiOiJKV1QiLC.......DGxZo3UerTxsBiUKhU7A"
    }
                    
                

    The token allows you to make requests to the Space Weather Data Share Web API.

  • listObtaining the files list arrow_drop_down

    With your access token you can now request the /climaespacial/SpaceWeatherDataShare/api/files/ endpoint using the method GET.

    
    GET http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/files/
    
                

    The GET request is sent to the /climaespacial/SpaceWeatherDataShare/api/files/ endpoint the query:

    Query Parameter Value
    application Required.
    the application ID.
    • List of Applications IDs
    • All-Sky Imager = 2
    • Callisto = 3
    • Ionosonde = 4
    • Magnetometer = 1
    • SPORT = 6
    start_date Required.
    Set the start date to the search. The accepted date format is (yyyy-mm-dd).
    end_date Required.
    Set the end date to the search. The accepted date format is" (yyyy-mm-dd).
    resolution Optional.
    The resolution is an application filter. See all applications filter ID
    station Optional.
    The station is a application filter. See all applications filter ID
    swfilter Optional.
    The swfilter is a application filter. See all applications filter ID
    swtype Optional.
    The swfilter is a application filter. See all applications filter ID
    network Optional.
    The network is a application filter. See all applications filter ID
    equipment Optional.
    The equipment is a application filter. See all applications filter ID
    Example

    This is a GET request example of the /climaespacial/SpaceWeatherDataShare/api/files/ endpoint, followed by the query:

                    
    GET http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/files/?application=1&start_date=2017-04-01&end_date=2017-04-23&resolution=1&station=1
    
                
    Headers

    The header of this GET request must contain the Authorization parameter always with “Bearer + token"as this example:

    
    Authorization: Bearer eyJ0eXAiOiJKV1QiLC.......DGxZo3UerTxsBiUKhU7A
    
    
    Response

    The response is a JSON with a list of files with Download files URL, created and size each files found on search as bellow."

        
    [
        {
            "url": "http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/download/SJC/2017/sjc23apr.17m",
            "created": "2017-04-23",
            "size_kb": "35kb"
        },
        {
            "url": "http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/download/SJC/2017/sjc22apr.17m",
            "created": "2017-04-22",
            "size_kb": "45kb"
        }
    ]
        
    
    Requests examples
    cURL
    
    curl -H \
    "Authorization: Bearer eyJ0eXAiOiJKV1QiLC.......DGxZo3UerTxsBiUKhU7A" \
    "http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/files/?application=1&start_date=2017-04-01&end_date=2017-04-23&resolution=1&station=1"
    
                
    Python
    
    import urllib.parse
    import urllib.request
    import json
    
    values = {
          "username": "your username or e-mail",
          "password": "your password"
      }
    
    headers = {
        'Content-Type': 'application/json'
    }
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    request = urllib.request.Request('http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/auth/login/', data)
    
    
    response_body = urllib.request.urlopen(request).read()
    with urllib.request.urlopen(request) as response:
        response = json.loads(response.read().decode('utf-8'))
        token = response['token']
        print(token)
    
    
    request_files = urllib.request.Request('http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/files/?application=1&start_date=2017-04-01&end_date=2017-04-23&resolution=1&station=1')
    bearer = 'Bearer ' + token
    request_files.add_header('Authorization', bearer)
    
    with urllib.request.urlopen(request_files) as response:
        list_files = json.loads(response.read().decode('utf-8'))
        print(list_files)
    
    
                
    Response

    On success, the response from the Space Weather Data Share Accounts service has the status code 200 OK in the response header, and the following JSON data in the response body

                    
    [
        {
            "url": "http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/download/SJC/2017/sjc23apr.17m",
            "created": "2017-04-23",
            "size_kb": "35kb"
        },
        {
            "url": "http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/download/SJC/2017/sjc22apr.17m",
            "created": "2017-04-22",
            "size_kb": "45kb"
        }
    ]
                    
                
  • cloud_download Downloading files arrow_drop_down

    After you retrieved the urls files list you can download the files in /climaespacial/SpaceWeatherDataShare/api/download/‹file-path› endpoint using the method GET.

    
    GET http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/download/‹file-path›
    
                
    Example

    This is a GET request example of the /climaespacial/SpaceWeatherDataShare/api/files/ endpoint, followed by the query:

                    
    GET http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/download/SJC/2017/sjc23apr.17m
    
                
    Headers

    The header of this GET request must contain the Authorization parameter always with “Bearer + token" as this example:

    
    Authorization: Bearer eyJ0eXAiOiJKV1QiLC.......DGxZo3UerTxsBiUKhU7A
    
    
    Response

    The response is the file.

        
    Content-Type →application/octet-stream
    Content-Disposition →attachment; filename="SJC/2017/sjc22apr.17m
        
    
    Requests examples
    cURL
    
    curl -H \
    "Authorization: Bearer eyJ0eXAiOiJKV1QiLC.......DGxZo3UerTxsBiUKhU7A" \
    "http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/climaespacial/SpaceWeatherDataShare/api/download/SJC/2017/sjc22apr.17m" -o sjc22apr.17m
    
                
    Python

    We had developed a complete package to download files from Space Weather Data Share API. You can see and download it from GitHub .

Authentication Error

Whenever the application makes requests related to authentication or authorization to Web API, such as retrieving an access token or refreshing an access token, the error response is:

                
{
    "detail": "Signature has expired."
}
                
            

Or

                
{
    "detail": "Authentication credentials were not provided."
}
                
            

Response Status Codes

Web API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:

Status Code Description
200 OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.
201 Created - The request has been fulfilled and resulted in a new resource being created.
202 Accepted - The request has been accepted for processing, but the processing has not been completed.
204 No Content - The request has succeeded but returns no message body.
304 Not Modified.
400 Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information; see Response Schema.
401 Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.
403 Forbidden - The server understood the request, but is refusing to fulfill it.
404 Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition.
429 Too Many Requests - Rate limiting has been applied.
500 Internal Server Error. You should never receive this error because our clever coders catch them all … but if you are unlucky enough to get one, please report it to us through a comment at the bottom of this page.
502 Bad Gateway - The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503 Service Unavailable - The server is currently unable to handle the request due to a temporary condition which will be alleviated after some delay. You can choose to resend the request again.

Frequently Asked Questions

Accessing your data without showing a login form
I want to interact with the web API and show some data on my website. I see that the endpoints I require authorization, but I don’t need/want a login window to pop-up, because I want to grant my own app access to files. Is there any way of doing this?

☑ You need an access token to download files from the API. To obtain an access token, follow the section "Obtaining Authorization". Once you get it, you can use your access token to retrieve data from the API.

I want to create a quick script to download files every day. Is there a way I can do this without having to open the browser to log in?

☑ Yes, the Space Weather Data Share Web API have support to login authorization through username and password. You can add your username and password to the script and as a response from the API you would obtain an access token.