How to Create an OpenCage Geocode Connector in AMPLIFY Integration Builder – Part 1

Axway AMPLIFY Integration Builder has over 150 connectors available for you to use in your integrations. However, there are times when you will want to connect to a data source for which there is no connector. You can use the HTTP Request step in the Flows, but that is somewhat manual and more prone to user error. It would be better is to have a connector available and use the Connector API Request step instead.

In this blog post, we’ll explore how to create an OpenCage Geocode API connector in Integration Builder. It’s a simple but very powerful API and it has a Swagger definition. Furthermore, it has a free tier for development and testing.

Prepare a Swagger JSON File from the OpenCage Swagger Definition

Integration Builder supports JSON Swagger files, so we will need to convert the YAML Swagger that OpenCage provides to a JSON format.

You can use SwaggerEditor for this as follows:

• Copy the the YAML response at https://opencagedata.com/swagger.yaml
• Paste the contents into Editor (left hand panel) in SwaggerEditor
• Select File -> Convert and Save as JSON to save a swagger.json to your computer

Import swagger to Create IB Connector

Now, we’ll create a new connector in Integration Builder by importing the swagger.json as follows:

• From the connectors tab, select Build a New Connector
• Click on Import
• Click on the Swagger and click on From Computer and select your swagger.json from before

• Select the one GET resource

• Click on Import

• Leave all defaults (for now) and press Save and Next

At this point, we’ve created our Connector!!!

Create an Instance and test the Connector

Now, we can create an instance and test out our connector as follows:

• Go to the Connectors tab and filter to find the new connector we built called OpenCage Geocoder

• Hover your mouse over the tile and select Authenticate, give your instance a name (e.g. OpenCage Test) and click Create Instance

• Select Test in the API docs and scroll to the bottom to find the GET /v{version}/{format} API and click on it to expand the docs

• Click Try it out and enter 1 for version, json for format, any place (e.g. Boston) for q and your OpenCage API Key for key

• Scroll down and press Execute and check the results

We can see that the response for q=Boston is:

{
  "requestId": "5ccb3fdbe4b050b498a7dfa0",
  "message": "Error parsing query: Boston"
}

This is not exactly what we’re looking for. It turns out that currently, q is reserved in Integration Builder and our API uses q as one of the query parameters for specifying the address (for Forward Geocode) or Lat/Long (for Reverse Geocode).

Don’t worry – because Integration Builder provides a way to map property names as follows:

• Click on Resources near the top of the page

• Press the edit button (pencil) on our API

• Rename the first q to query since q is reserved. Our Integration Builder API will use query parameter which will map to parameter q in the OpenCage API.

• Press Save and then API Docs and go try out the API again. You’ll see that one of the required parameters in query this time (and not q). Fill in the query parameters again (as before and check your results)

• Press the Execute button

Now you can see a valid response from OpenCage.

Use the OpenCage Connector in a Flow

In the following screenshot, you can see how to access the connector in a flow:

Note that the API is set to /v1/json and the Query is set to ${steps.prepareQuery.query} which is computed in a prior step as shown in the screenshot below:

Summary

We saw how easy Integration Builder makes it to create a connector with just a few clicks.

The connector and test flow can be found here.

In future blog posts, we’ll enhance this connector and make it more user friendly.

Special thanks to Aleksandr Nartovich for his help on this blog post.