Tutorial: Generate an Authentication Token and download an image with ExtractImage - v1.4

Owned by Scott Jonker
Last updated: Apr 06, 2023
5 min read

About

In this Quick Start Tutorial, you will learn about the Authentication Services and then make a call using the Extract Images Service. For the sake of instruction this tutorial will demonstrate two methods to interact with the API: curl and Postman. It is important to note that there are many alternatives to curl and Postman and the Vexcel API does not rely on any one URL handler. After working through this tutorial, you’ll be ready to review the rest of the API services and get started building your own applications and integrating Vexcel imagery into your workflows!

This tutorial will cover two steps:
Step 1 - Generate an Authentication Token using curl
Step 2 - Download a single discrete image using the Authentication Token.

Use of this tutorial requires a valid Vexcel API Subscription. Contact Vexcel Customer Service to inquire about credentials.

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:

  1. Install curl

    1. Official Installation Instructions: https://curl.se/docs/install.html

  2. Open a command line interface window (e.g. Windows: Command Prompt, Mac: Terminal)

    1. Paste this curl command:

      curl --proxytunnel https://api.gic.org/auth/Login/ --data "username=username&password=password"

    2. update the values for the username and password parameters to reflect your login credentials.

    3. 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:

  1. Log-in (or sign-up) to web.postman.co and open a new GET request tab.

  2. In the 'Enter request URL' box, paste:

    https://api.gic.org/auth/Login?username=username&password=password

    1. The ‘Query Params’ table will auto-populate, update the values for each parameter to match the table above; this will automatically update the URL.

  3. 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.

 

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

Parameter

Value

layer

bluesky-ultra-g

mode

one

orientation

NN

EPSG

4326

xcoordinate

-89.915411

ycoordinate

35.170619

zoom

0

token

{token}

width

1000

height

800

curl:

  1. Open a basic text editor (e.g. Windows: Notepad, Mac: TextEdit):

    1. 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

    2. Update the token parameter to reflect the authentication token you received in Step 1.

    3. 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.

  2. Open a command line interface window (e.g. Windows: Command Prompt, Mac: Terminal)

    1. Navigate to the directory in which you wish to download the image (e.g. C:\Users\Name\Downloads)

    2. Paste in the modified curl command and press Enter.

Postman:

  1. Log-in to web.postman.co and open a new GET request tab.

  2. In the 'Enter request URL' box, paste:

    1. The ‘Query Params’ table will auto-populate, update the values for each parameter to match the table above; this will automatically update the URL.

  3. Click the ‘Send’ button

Results:

curl:

Success:

The image is located within the directory you navigated to prior to running the curl script:

 

Failure:

  • 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:

  • 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.

 

  • Incorrect or expired authentication token. Review the token and regenerate a new token if necessary.

 

  • 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

 

Need help? Create a support ticket | support@vexcelgroup.com