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 .
POST http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/api/auth/login/
The header of this POST request must contain the following parameter:
Content-type: application/json
You can login with your username or e-mail in 'username' JSON key.
{
"username": "your username or your e-mail",
"password": "your-password"
}
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/
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)
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.
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.
|
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 |
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
The header of this GET request must contain the Authorization parameter always with “Bearer + token"as this example:
Authorization: Bearer eyJ0eXAiOiJKV1QiLC.......DGxZo3UerTxsBiUKhU7A
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"
}
]
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"
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)
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"
}
]
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›
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
The header of this GET request must contain the Authorization parameter always with “Bearer + token" as this example:
Authorization: Bearer eyJ0eXAiOiJKV1QiLC.......DGxZo3UerTxsBiUKhU7A
The response is the file.
Content-Type →application/octet-stream
Content-Disposition →attachment; filename="SJC/2017/sjc22apr.17m
curl -H \
"Authorization: Bearer eyJ0eXAiOiJKV1QiLC.......DGxZo3UerTxsBiUKhU7A" \
"http://www2.inpe.br/climaespacial/SpaceWeatherDataShare/climaespacial/SpaceWeatherDataShare/api/download/SJC/2017/sjc22apr.17m" -o sjc22apr.17m
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
☑ 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.
☑ 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.