3. Making Your First Request

In this article, you will learn how to use the Postman application, where to get your authentication token, and how to make your first request to the Lightbox APIs.
Before proceeding, make sure you have a valid, non-expired, LightBox API authentication token. If you do not have one, please visit Registering for an Evaluation for more details.

Postman

The easiest way to begin interacting with—and developing for—the LightBox APIs is with Postman. Postman is a free, third-party application that makes it easy to submit API requests, receive response data, and begin understanding how the LightBox APIs are structured.

To get started, download and install Postman. During the installation process, you will be prompted to create an account. Postman can also be accessed via a browser, though the web-based version does not include all of the features of the desktop application.  

Once the installation has been completed, open Postman.

Navigating Postman

Within Postman, the first step is to import an API collection. Postman collections are a tool for organizing sets of requests. Importing a collection will save you a great deal of time, as you will not need to manually enter the endpoint URLs, request types, associated parameters, etc. All of the LightBox APIs contain a Swagger definition that will be used to import into your Postman collection. For our example below we will use the Geocoding API.

Navigate to the Geocoding API page, then select and copy the geocoding swagger link (step 1).

Within Postman select APIs (step 1) then select Import (step 2)

Next copy and paste the Geocoding Swagger/ open API URL (step 3) and click continue (step 4)

Click on Import (Step 5)

Once the import is complete, expand the newly imported API (step 6) and click on Auth (step 7), paste your consumer key/apiKey in the Auth value box (step 8), and then click Send. This is the easiest method to authenticate your first time. An alternate method is to set the Auth on the "addresses node," and for each of the API endpoint requests set the Type = Inherit from parent.

After submitting the request, the response will appear at the bottom of the Postman application.

Postman provides controls to easily view, navigate, and manage the response.

1. By default, the response body is displayed. Click on Cookies, Headers, or Test Results tabs to display the associated content.
2. Select the layout of the response body content. The default is “Pretty,” which highlights links and makes them clickable. Clicking a link creates a new GET request.
3. The response body is displayed in JSON format by default. Click the dropdown menu to view and select a different format from the available options: XML, HTML, Text, Auto.
4. Click the two boxes icon to copy the contents of the response to your clipboard. Click the magnifying glass to open a search modal.
5. Click Save Response to expose a menu containing two commands:

Save as example: According to the Postman documentation:

”In Postman, an example is a tightly-coupled request and response pair. Each example is made up of a request part (method, URL, parameters, headers, and body) as well as a response part (status code, body, and headers). You create examples by adding them to requests in collections, and one request can have multiple examples.”

Save to a file: Download a copy of the response. 

Note: The file will be downloaded as a JSON file, regardless of the format it is currently displayed as in Postman.

Postman provides a robust knowledge base and Getting Started tutorials at learning.postman.com

Request

For this example, we will be calling the Geocoding search endpoint https://api.lightboxre.com/v1/addresses/search by address. This will return a parsed address, confidence score, latitude, longitude, precision code, and reference requests back to the related core objects. 

Authentication

LightBox APIs use token-based authentication to authenticate all requests. The token to be passed via an HTTP header with key x-api-key and the value will be the API token. 

Using curl

A good way to send a request is by using curl (Client URL).

The below example makes a GET request to retrieve a parcel object by the parcel LightBox ID. This request takes in a single path parameter, which is the value of the LightBox ID. You will also need to replace the <authentication token> with your token. When you execute this you should get a JSON response of the parcel object that is assigned to this LightBox ID.

curl "https://api.lightboxre.com/v1/parcels/us/02034UK8D0FPUGRCMY8L76" -H "x-api-key: <authentication token>"

Next Step:  4. Using the LightBox Developer Portal Swagger documentation