How to order products using Finder API on CREODIAS

../_images/button_orange_cf24.png

In order to start ordering products using Finder API you may use cURL library that is mainly responsible for sending HTTP requests. By default it is preinstalled on each virtual machine.

Note

Information

cURL parameters:

  • -X assign a REQUEST type to your operation

  • -H Content Type: declare a output format

  • -H Keycloak-Token: define a authorization type. For our security purpose we use KeyCloak token. A proper How-to procedure is located in the Obtain a KeyCloak token section in one part of article.

Client is able to perform one POST operation:

order processed products

Sentinel-2 products are available in processing level 1. By ordering processed product we send a request to obtain a product in processing level 2.

order external products

Product is visible in EO Finder but is not available in our repositories yet. Its status is recognized as “Orderable”.

Documentation

For comprehensive API description you can visit this page: Finder API.

Ordering processed product

Syntax:

curl -X POST https://finder.creodias.eu/api/order/ -H 'Content-Type:application/json' -H "Keycloak-Token: ${KEYCLOAK_TOKEN}" \
  -d '{"priority":number,
  "order_name":"name",
  "processor": "sen2cor",
  "identifier_list":["title_without_safe_extension"]}' | python3 -m json.tool

Title is a representative fullname of the product in our repository. In the identifier_list parameter above you have to place title without its extension SAFE extension e.g

S2A_MSIL1C_20190521T063631_N0207_R120_T40RES_20190521T094626.

Attention

You must fill in a “processor” field to accomplish an order. Its value should be set on sen2cor which is responsible for processing level 1 product to level 2 in Sentinel-2 collection.

Example for one product from Sentinel-2 collection:

curl -X POST https://finder.creodias.eu/api/order/ -H 'Content-Type:application/json' -H "Keycloak-Token: ${KEYCLOAK_TOKEN}" \
  -d '{"priority":1,
  "order_name":"test_order_for_FAQ",
  "processor": "sen2cor",
  "identifier_list":["S2A_MSIL1C_20190228T110001_N0207_R094_T31VEG_20190228T111324"]}' | python3 -m json.tool

Checking the order list

Syntax:

curl -X GET https://finder.creodias.eu/api/order/ -H "Content-Type: application/json" -H "Keycloak-Token: ${KEYCLOAK_TOKEN}" | python3 -m json.tool

Verifying the status of a particular order

Syntax:

curl -X GET https://finder.creodias.eu/api/order/order_id/order_items/ -H "Content-Type: application/json" -H "Keycloak-Token: ${KEYCLOAK_TOKEN}" | python3 -m json.tool

Example for order with ID 203:

curl -X GET https://finder.creodias.eu/api/order/203/order_items/ -H "Content-Type: application/json" -H "Keycloak-Token: ${KEYCLOAK_TOKEN}" | python3 -m json.tool

Attention

If the amount of ordered products exceeed over 10, you will have to add page parameter to iterate over whole list. One page can write only ten items to standard stream output.

e.g.

curl -X GET https://finder.creodias.eu/api/order/86283/order_items/?page=2 \
-H "Content-Type: application/json" -H "Keycloak-Token: ${KEYCLOAK_TOKEN}" | python3 -m json.tool

You can see a total count number on every GET query in the first row:

"total": 89,
"page": 0,
"size": 10

The API will no longer provide “previous” and “next” URLs. The user should iterate over the results until the number of items in the response is smaller than “size” or the following condition is met: “size” x “page” >= “total”.

Obtain a KeyCloak token

Important

Please keep in mind that the token lifespan is ten minutes. After that, you should repeat whole procedure.

export KEYCLOAK_TOKEN=$(curl -d 'client_id=CLOUDFERRO_PUBLIC' \
                             -d "username=${OS_USERNAME}" \
                             -d "password=${OS_PASSWORD}" \
                             -d 'grant_type=password' \
                             'https://identity.cloudferro.com/auth/realms/DIAS/protocol/openid-connect/token' | \
                             python3 -m json.tool | grep "access_token" | awk -F\" '{print $4}')

Warning

Warning concerning curl statement above:

Variables $OS_USERNAME and $OS_PASSWORD already assume that you have used “source” command or “.” on the RC file with your OpenStack credentials. For more I refer to How to install OpenStackClient for Linux on CREODIAS.

Here you can locate the button to proceed download in Horizon panel:

../_images/orderapi.png

You can also obtain token without using Python environment and authenticating with OpenStack RC File using simpler curl command:

curl \
   -d 'client_id=CLOUDFERRO_PUBLIC' \
   -d 'username=<your_CREODIAS_username>' \
   -d 'password=<your_CREODIAS_password>' \
   -d 'grant_type=password' \
   'https://identity.cloudferro.com/auth/realms/DIAS/protocol/openid-connect/token' \
   | python3 -m json.tool | grep "access_token"

Please note that using this curl command will not save your token in environmental variables and requires entering your username and password.

Troubleshooting

In the case of failure you may encounter those symptoms:

A)

{"ErrorMessage":"orderProduct- Forbidden","ErrorCode":403}

Take a look at your Keycloak token and verify if it is correctly stored in variable:

printenv KEYCLOAK_TOKEN

B)

{"ErrorMessage":"processModuleRoute - Not Found","ErrorCode":404}

Verify your Module Path. Your request might refer to the operation that does not exist in API installment. (Spell checking recommended)

C)

Warning

Be aware that curl parameter does not escape correctly the & as the last character in the password. In this case you should obtain a respond:

{
    "error": "invalid_grant",
    "error_description": "Invalid user credentials"
}