How to order products using Finder API?

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.

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.

Comment: 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 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 FAQ How to install OpenStackClient (Linux)?

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

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:

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

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

printenv KEYCLOAK_TOKEN

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

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

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"
}

TAGS