Insomnia Geocoding Tutorial

Using Insomnia to access the OpenCage geocoding API

Insomnia is a free and open-source desktop client for debugging and testing REST APIs. Our API is very straight-forward, with only a single entry point and authentication via the key parameter you supply as a variable in your request. Many APIs are more complex, and Insomnia can be a useful tool for interrogating them.

Nevertheless, as we know developers tend to have a preference to use the tools they are familiar with, we thought it might be helpful to publish an Insomnia "Workspace" to make it as simple as possible for any developer who wants to access our API via this tool.

1. Sign up for an OpenCage Geocoding API key, or if you already have one log in.
2. Download and install the Insomnia REST client from the Insomnia website. Start up the Insomnia application
   
3. Download the OpenCage workspace JSON file, which you can find here.
   Import the OpenCage workspace into your Insomnia client by clicking on "Import from File"
   

4. Notice on the right you can now see a request named "OpenCage Reverse request".
   
   Click on it.

5. In the center of the application you can now see the request and click on the "Query" tab to see the various parameters.
   Notice that the key parameter uses a variable named OPENCAGE_API_KEY.
   

6. You need to set the variable value in the "Environment". In the upper left click on the Environment and then select "Manage Environments"
   
   You will see a JSON editor. Set the value of OPENCAGE_API_KEY to your OpenCage API key.
   

7. Ok, now you're ready to start querying the OpenCage server. Run a query and you should see a response from the OpenCage server
   
   Now you can change the parameter values or add some of the optional parameters we support.

8. Happy geocoding!