About
Step 1. Generate an Authentication Token
The authentication token will be used by every Vexcel API Service. As such, it is important to understand how to generate a token. Follow these steps to learn how to generate an authentication token using curl or Postman:
Before beginning, have your login-credentials ready; if you do not have login-credentials contact Vexcel Customer Service.
curl:
Install curl
Official Installation Instructions: https://curl.se/docs/install.html
Open a command line interface window (e.g. Windows: Command Prompt, Mac: Terminal)
Paste this curl command:
curl --proxytunnel https://api.gic.org/auth/Login/ --data "username=username&password=password"
update the values for the
usernameandpasswordparameters to reflect your login credentials.Press the Enter key
If your password contains the & character it is necessary add the flag --data-urlencode.
e.g. curl -p https://api.gic.org/auth/Login/ -d "username={username}" --data-urlencode "password={password}"
Postman:
Log-in (or sign-up) to web.postman.co and open a new GET request tab.
In the 'Enter request URL' box, paste:
https://api.gic.org/auth/Login?username=username&password=password
The ‘Query Params’ table will auto-populate, update the values for each parameter to match the table above; this will automatically update the URL.
Click the ‘Send’ button
Results:
Success: {"token":"4c58a2327affca6ccde7fe6673c81e09a8d9654d391a21829c08ec9101482a062e6c68f0e551af6b11eae1467ea069d844a47082d9c97124fd1d20666774f4d923e1fb0874ff65a9ae58254cb8853066","expiration_date":"2021-05-08T17:44:32"}
Record your authentication token for future API use
Proceed to Step 2. to download an Image.
Failure: {"status": 701,"message": "Login Failed"}
Check your credentials and try again.
Failure: {"status": 111,"message": "Wrong parameters for this request"}
Wrong Parameters, there is an issue with your syntax. Carefully examine each character of the command and verify that there are no misplaced characters or erroneously included characters.
Some notes about the Authentication Token:
You will use the token in all future API calls
This token will be valid for 12 hours (24 hours for federated authenticated accounts), upon expiration a new one will need to be generated.
Detailed documentation on the Authentication Token Services including:
The Login Service will generate a new token (as demonstrated above) with additional examples in Python, and JavaScript
The Authenticate Service will report if an existing token has expired or not.
The Logout Service will terminate a token and its active session.
Step 2. Use the Authentication Token with the ExtractImages Service.
Now that we have an authentication token, we’re ready to put it to use and make our first call to the API. For this example, we’ll request an image from the ExtractImages service with a predefined set of parameters:
Parameter | Value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Feel free to modify these variables, using the ExtractImages documentation for more information. | |
curl:
Open a basic text editor (e.g. Windows: Notepad, Mac: TextEdit):
Paste this curl command:
curl --proxytunnel https://api.gic.org/images/ExtractImages/bluesky-ultra-g/ --data "mode=one&orientation=NN&EPSG=4326&xcoordinate=-89.915411&ycoordinate=35.170619&zoom=0&width=1000&height=800&token=4c58a2327affca6ccde7fe6673c81e09a8d9654d391a21829c08ec9101482a062e6c68f0e551af6b11eae1467ea069d844a47082d9c97124fd1d20666774f4d923e1fb0874ff65a9ae58254cb8853066" --remote-name --remote-header-name
Update the
tokenparameter to reflect the authentication token you received in Step 1.Update any of the other parameters as you desire; doing so may result in errors and/or the downloading of a different image than exemplified.
Open a command line interface window (e.g. Windows: Command Prompt, Mac: Terminal)
Navigate to the directory in which you wish to download the image (e.g.
C:\Users\Name\Downloads)Paste in the modified curl command and press Enter.
Postman:
Log-in to web.postman.co and open a new GET request tab.
In the 'Enter request URL' box, paste:
https://api.gic.org/images/ExtractImages/bluesky-ultra-g?mode={mode}&orientation={orientation}&EPSG={EPSG}&xcoordinate={xcoordinate}&ycoordinate={ycoordinate}&zoom={zoom}&width={width}&height={height}&token={token}The ‘Query Params’ table will auto-populate, update the values for each parameter to match the table above; this will automatically update the URL.
Click the ‘Send’ button
Results:
curl:
Success:
% Total % Received % Xferd Average Speed Time Time Time CurrentDload Upload Total Spent Left Speed 100 85812 100 85538 100 274 28512 91 0:00:03 0:00:03 --:--:-- 26403 curl: Saved to filename 'NN_20191002_175514_38222055B275B26_extract.jpg'
The image is located within the directory you navigated to prior to running the curl script:
Failure:
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0Warning: Remote filename has no length!
100 340 100 65 100 275 65 275 0:00:01 --:--:-- 0:00:01 701
curl: (23) Failed writing body (0 != 65)
Wrong Parameters, there is an issue with your syntax. Carefully examine each character of the command and verify that there are no misplaced characters or erroneously included characters.
Postman:
Success:
No text output
Use the ‘Save Response’ button in the results section of the interface to download the image.
Failures:
{
"status": 101,
"message": "Error extracting image"
}
There is an issue with your URL; Carefully examine each character of the command and verify that there are no misplaced characters or erroneously included characters.
{
"status": 403,
"message": "Unauthorized"
}
Incorrect or expired authentication token. Review the token and regenerate a new token if necessary.
{
"status": 600,
"message": "No result available for this request"
}
There is an issue with one of the parameters which is causing the API to filter out all images. Review for a typo.
External Resources
Command Line Tool and Library (curl)
https://curl.se/Postman API tester:
web.postman.co