Address Validation with RPG-XML Suite and SmartyStreets

by | Nov 15, 2017

Whether you’re shipping goods or mailing flyers, you need confidence that your product will end up in your customer’s hands. That’s why address validation is so important in today’s industry. RPG-XML Suite is here to help.

RPG-XML Suite is an IBM i solutions toolkit that is built with purpose for RPG developers. RXS allows for easy calling of JSON web services from RPG, eliminating the cost and time of manual coding and facilitating communication with countless APIs.

A popular platform for address validation is SmartyStreets. Their US Street Address API uses the USPS postal database to return verified and corrected address data. This flexible API allows you to validate up to 100 addresses per request, which will make bulk processing a breeze.

RPG-XML Suite also makes this process a breeze by offering simple, easy-to-use APIs to compose and parse JSON data and facilitate the HTTP communication to the SmartyStreets API.

Here are the RPG-XML Suite APIs we will be using:

SMRT Service Program

Here is the service program we’ve put together. It contains a single exported subprocedure, SMRT_StreetAddress(), which takes in an address to be validated, composes the JSON request, makes an HTTP request to the SmartyStreets API, and parses the response JSON. We will be referring to snippets of this program throughout this post.

And here is the copybook:

For simplicity’s sake, we’ve designed our service program to validate a single address per call. If you wanted to process multiple addresses, you could read data from a physical file, or pass in an array of data structures to process.

Composing the Request JSON

Let’s first examine the compose subroutine. Because SmartyStreets can accept multiple addresses in a single request, they expect request data to be an array of address objects, like so:

We’ll only be sending a single address object, but our base JSON structure is still an array, which is why our JSON composition is initialized with the RXS_JSON_STRUCTURE_ARRAY type:

RootDS represents the base array of our JSON request. We will create a child JSON object next:

Next, we will compose the address fields to the child AddressDS structure, using the appropriate RXS_ComposeJson[Type]() API:

Then, we will retrieve our composed JSON with RXS_GetJsonString():

RequestData now contains this JSON structure:

Calling the SmartyStreets API

Now that we have our composed JSON request, we will make an HTTP call to the SmartyStreets API. This is accomplished in the transmit subroutine. We specify the URI for SmartyStreets, the HTTP method – in this case, POST – the content-type, and optionally we can specify a LogFile, where RPG-XML Suite will store a log of the request and response data and headers. This logfile is useful for debugging.

ResponseData now contains the validated address data returned by the SmartyStreets API. We use a simple error check to make sure that the HTTP status code was 200 – which indicates a successful request – and move on to parsing.

Parsing the Response JSON

When parsing JSON data, you need to build a parsing handler subprocedure. This handler subprocedure is called by the RPG-XML Suite parsing API, and it determines what to do with data retrieved from the JSON object. All JSON parsing handlers have this prototype:

The general structure of a parsing handler will be a select; block that checks target paths in the JSON object and retrieves the data into a field:

The [*] notation represents an array, either a root array or a child array. Since our response JSON is a root array, we will see this notation at the start of each of our paths in the parsing handler. Make a when condition for each JSON path that contains data you want to retrieve. We are saving this data to a global response data structure, but you could also use the handler to write this data out to a physical file. Our global response data structure will be returned to the calling program once parsing completes.

The parse subroutine handles the parsing operation in our subprocedure. It specifies which parsing handler to use, calls RXS_ParseJson(), then passes the response data back to the calling program through the pResponseDS parameter.

Example Program

Here is a simple example program that calls our SMRT_StreetAddress() subprocedure and writes response information to the job log:

If the validation was successful, your job log output should look something like this:

SmartyStreets Output

SmartyStreets Output


  • Call web APIs from RPG
  • Process XML and JSON
  • Offer web services

Litmis Spaces

Affordable IBM i cloud hosting

CyberSource Toolkit for i

  • Process credit cards from native RPG
  • Integrate CyberSource payment services

Follow Us

Interested in learning more about RPG-XML Suite & SmartyStreets? Contact us!

  • This field is for validation purposes and should be left unchanged.

Get Social

Share to your favorite social platform