Below is a full transcript of the video Tutorial: Address Suggestor using Google’s Places API & Service Objects’ Address Validation API.
Today we are going to be building out an address suggestion input form tool. I’ve already built this out, but I will take you from the beginning, and show you step-by-step what you must do to implement this. In this demonstration, I will be using Visual Studio. This is the type of form that will predict the address you are trying to type. Besides address suggestion, it is also referred to as type-ahead, or predictive typing, and a couple of other things as well. We will use the Google Places API in conjunction with our DOTS International Address Validation to the predictive addresses, and address validation.
First, why is a form like this helpful? Why would someone want this? The main reason is so that you can have clean, accurate data added to your systems up front, instead of trying to clean the data up later, which can be very costly to do. Another reason, is to help speed-up the data entry, and data accuracy on the form. The data entry could be coming from your prospects and clients on a form you have published on the web. Maybe someone is purchasing a subscription, or ordering a product or service. The data could be coming from call-center staff, who are on the phone entering the data for the same types of reasons. There are really many reasons that an address suggestion form can help.
Now that we have some idea as to why we would want to implement an address suggestion tool, let’s switch over to how it works. There are three main parts to this integration. The Google Places API, the DOTS Address Validation – International API, and the web form itself. Some people wonder why we just can’t stop at the Google Places API, and the form, and exclude the Address Validation portion. One of the paramount reasons that the Google Places API is not enough is because it does not give you mailing accuracy. The second reason is that it makes approximations as to where an address could be, versus if it exists or not.
On the first point, accuracy, Google does not verify, or suggest addresses that are mailable. They typically return an address’s physical location on a map, but not if it is a valid mailing address. The second point is the guessing that the Google Places API does. It approximates where an address could be based on other addresses on the street. 508 Kings Road, Brighton, UK, looks like a legitimate address, but when you look at it on Google Maps, then it does not look like the address is actually associated with anything. Those are the main reasons why the Google Places API isn’t enough. You need to bring DOTS Address Validation – International to save the day, and make the solution truly useful.
In this demonstration, we are going to get a Google API account, and get an API key for the Places API. After that, we are going to get our DOTS Address Validation – International key from Service Objects. Here is an important note, you can alter the validation sections we are going to go over, to meet your specific needs. Here, I’m demonstrating how this can be done with DOTS Address Validation – International.
However, if your need is just in the US, then you can, instead, get a key for DOTS Address Validation – US, DOTS Address Detective, DOTS Address Insights, or DOTS Address Validation Plus. If all you need is Canadian address validation, then DOTS Address Validation – Canada should suit perfectly as a substitution. Any of our services that take an address as an input pairs perfectly with the Google Places API. Taxes is another one, DOTS FastTax is a great example that can also help you out. I could go on, but I’ll leave it to you to explore.
Once we have those keys, we will move on to setting up the form, and getting some of the UI Boilerplate stuff taken care of. After that, we will jump into the needed methods from the Google Places API. Lastly, we will go over how to setup the call to DOTS Address Validation – International. Though most of the work is done in Java Script, we will show you how to create a proxy, so that our license key is not exposed to the outside world for anyone to use and take. I guess this will be a kind of a two-in-one demo.
Now we’re going to switch over to the Google API account on page, this is where you can get any API that Google offers. Here we’re interested in the Places API, and the Maps Java Script API. You can see we have those already selected here. Here’s a bunch of unselected APIs down here, unused. We have the ones that we want already selected and added. What we’re going to want to do … I’ll go back for a sec. We’re going to want to first create a project, and we’ve already done that. We’ve called it Service Objects Address Suggest, and we added the APIs to this.
On their dashboard here, you can see the transactions that have occurred against the API. You can have the resolution up to 30 days, down to an hour. You can download this kind of information to really keep track of how your APIs are being used. We’re going to want to click in, and get some deeper resolution on the Google Places API, because we’re going to need the key. We’re going to need to pull the key out. When we switch over to that page, we have the key here, I suggest copying that off, saving it for later. You can name it whatever you want.
Then there’s some restrictions, non-HTTP, IP address, Android, iOS. You can set some restrictions up here that’s going to help with securing your API key when people are looking at your Java Script. They can see your key, so locking it down to particular page, or an IP address, those things are going to help secure your key so other people don’t take it and use it. For now, while we’re in development mode, we’re going to use the “None” selection so we can just get through our development. But before we go to production, we’re going to want to lock this down a lot better. That’s pretty much it. Save your API key off for later, and then we’ll show you where that plugs in as we go through the steps.
Jumping back really quick, I did want to mention that you can use the Google API key to a degree for free, but you’re going to want to go through the usage, and billing plans that they have for the key itself. Depending on your volume, you’re going to want to watch out for this, because it will cost money per transaction. There’s a few links here that I found useful when trying to analyze which plan to go with. You’re going to have to read through this yourself. It seems to be changing a lot recently, so you’re going to want to keep up to date with these pages here, and make sure you’re always on the right plan.
This page here, the Places API usage and billing was good. The pricing that scales to fit your needs helped a lot for figuring things out, and also this Pricing and Plans page as well gave a lot of good information that can help figure out which plan you need to go with, and what you need to look out for. But there’s a lot here, and it can be kind of confusing. I would really take your time, and look through these pages. Make sure you’re setting yourself up for the right plan.
Now we’re going to switch over to getting the DOTS Address Validation – International API key from Service Objects. This is our homepage, a lot of useful links to the products, solutions, developer support, blogs. Blogs have a lot of information. All of us in the company really help provide information, and write a lot of information about our services and products here, and really what’s happening in the industry that can help you guys out. That’s really worth taking a look at.
But we’re going to jump right in, and we’re going to go get the API key. I’m going to select this section for Address & Geocoding. We also have Lead Validation, Phone, Demographics, Ecommerce, Email. We’re interested in addresses, so we’re going to go in this section, and go from there. Coming into here, we have Address Validation, Address Geocode, Address Insights, NCOA Live. Address Detective. A lot of this can be used with what we’re trying to get accomplished here, since they’re all address-type services. But, for our purposes right now, we’re going to jump in, and do the Address Validation – International.
We’re going to click on this link. It’s going to take us to the product page for that service. Down here, you can fill out your information, and get your trial key. It will get emailed to you. Once you fill out this page, you’ll also get redirected to the information that you need as well. If you don’t see it in your email, maybe you got … You’re going to want to check your Junk Mail, just in case, but if you don’t find it in either place, you could still get the information after you get redirected here, so you’ll be okay.
Otherwise, you’ve got this input form, where you can try one-off lookups. You have your own information that you can send through the API in these fields here, or you can select this drop-down, and select some pre-populated data, and run that through to see what you can get back. Then at the bottom, we just have some example request, and responses in JSON and XML, based on the information that’s in these fields when you submit, just to take a look at what the service will give you back.
We do have an API key already, so I’m not going to fill out this form, it’s just good to know where you can get the API key. We already have all the code worked out for this project. I’m going to, instead of recreating everything one-by-one, I’ll just go through everything that I’ve created, the order in which you’re going to want to create these things, and I’ll highlight the different interesting points along the way. You could then take the code, and really understand what’s going on here. It’s not all the complicated, you guys should be able to use this, and use any of our other services that could use address suggestion, and implement that here as well, it would be really easy.
Just follow along as I go through the steps. I’ll point out the different things that are really unique, or something that you’re going to watch out for. The first thing we’re going to do, or what we did, was create some files that we’re going to need. Let’s just start with the style sheet folder. This stuff, I’m really not going to over style sheets, this is just to make the page look the way we want it to look. You guys could take what we have here, or do whatever you want on your side with the styles and classes here. The only interesting part here really, is the first part, where we create, basically default all the browser settings that may be sitting in the background, just to make sure that you have a consistent style sheet all the way through the different browsers. That’s all this is. The rest of it is any specific things that you wanted to change on your own with the look and feel of the page.
All this code that we’re going to be going over is going to be included in a file that you can download, and adjust, make your own. You can adjust anything we have here to suit your needs, which is likely what you’re going to want to do. All this code is freely available, so please take it, and make it your own. The next thing we’re going to go over is the addresssuggestinternationalform.HTML, the HTML markup page. We’re going to start by looking at the first include here that we have. Here it is, the jQuery script. We do use jQuery in the background, and when we get to the Java Script section of this tutorial. Keep that in mind. If you’re not familiar with jQuery, it’s really simple, a lot of good documentation out there to learn that, you can be up and running in no time. Just take a look at their documentation and you should be good.
The second script we have here is the API Handlerinternational.js. This is the file we’re going to be writing later on, once we get to the JavaScript section. Don’t worry about that one for now. That’s followed by the div for the result modal. That’s the modal that’s going to popup after we click the Verify button so we can see the results from the validation. After that, we have our header area, with the logo, and the title of our application, in this case, it’s Address Suggestion Demo. Then we have the country input field, the drop-down select. Here I’ve hard-coded all the different countries that we want to deal with. You’re going to want to populate this list dynamically when you’re doing this for production, or for live, or for your company.
I did this real quick to hard-code it in, but it’s definitely going to be better as something that you can dynamically populate. Then we’re followed by all the different input fields we have, autocomplete, this is really our address one field, this is the field where people are going to be typing their address in. Google Places API is going to be keying off of this, and showing you suggested addresses based off of what you’re typing in here. That’s what autocomplete field here is, it’s our address line one. Then we have our address line two, which really is supposed to be containing our apartment, or our suite information, the city, the state, the zip, that should be all pretty straight forward. Then we have a div, which is really our verify button, our validate button here.
At the bottom we have script to the Google Places API. Here we have our API key. This is going to be hidden when you’re looking at it, but this is where you’re going to want drop your key that you’ve made note of earlier when you set up your Google Places API key, that’s going to drop right into here. That’s all you’re really going to need to know about this page. There really isn’t anything special, or unique about it, other than the styling, and that we link up to the autocomplete field here to do the autocomplete against the Google Places API.
I do want to go back to this section here about the Google Places API key. I really want to highlight that this is exposed when somebody runs the form that goes to the page that has your form. So when looks at the background code, they can see your API key. As I mentioned earlier, we have no restrictions on our API key right now, so someone could, if they had this, use it for their own purposes, start running up transactions on the key, and that could end up being very costly. When you do move to production, do not forget to go back and change the settings on the key in the Google API account. You’re going to want to make sure it’s locked down as best you can, so that you don’t get calls against your API key unwittingly.
Now we’re going to jump into the API Handlersinternational.js file. This is the JavaScript file that’s going to really contain a lot of the interesting things that happen in the background on the screen. We created a JavaScript folder for that, so we can keep things nice and organized. JavaScript probably needs an S, capital S there. Oh well, we’ll keep it the way it is for now, and there’s our file.
The first thing in the file are these three variables that we set up, the autocomplete object here, the variable here, it’s just going to contain the autocomplete object that’s sent back from the Google Places API. The component form, this is really just an array of the IDs in our forms. If we really want to reset any of those fields, we can easily, quickly loop through those resetting them. Then selected country, we have set to US, but that’ll be overwritten whenever we have a new country selected from that drop-down.
The first thing we’re going to do is jump down to this function at the bottom. This function executes once the page has completed loading. What it does is it adds an event to whenever someone changes the country in the drop-down for countries, to another country, then this is going to execute, and it’s going to reset all the fields in the form, which makes sense. You don’t want to have data for the wrong country displayed. Then it executes this initAutocomplete method.
I’m going to jump into this one right now, and just get it out of the way. We’ll do that next. What the initAutocomplete method does is really just initializes the Google Places API, and it returns the autocomplete object into autocomplete here based off of the autocomplete element that we pass in through the IP. We set the Google Places API to respond with geocode type, which is the address type data that we’re looking for. You could put other things in here, and it gives you varying degrees of data back. The geocode is exactly what we’re looking for, so that’s what we have here.
Then based off of the country selected, you can restrict the API to a country. You can have a list here of countries. I think of up to five, you’ll want to double-check the documentation for this field. But what we need it for right now is the one country that is selected from the drop-down. After that, we add a listener to the autocomplete object. It’s going to basically react to selecting one of the addresses, once a address is selected from one of the suggestions this fill in address method gets executed. Basically, what we do is we get the place object back from the autocomplete object, and then we reset the form.
After we reset the form, we parse the place object, basically parsing apart the places data that comes back in JSON, and we populate the input fields based off of the address that was selected. Varying pieces of data come back, so you have several cases here that you might want to deal with, or expand upon, or not use, depending on your purpose. This is just an example of what can be done. After that, we populate the fields with parsed address from the response.
The bottom of the page really just has … what’s left is the modal start method, that really just deals with opening and closing the modal page, the result page that comes up after verification. The next part to really talk about is the click event, when someone clicks the Verify button, the click event will fire, and then we’re going to pull in the variables from the screen, the fields, and we’re going to populate them to the local variables here. Once we have those variables populated, we’re going to then toss them into the call address validation method. This is where the magic on the Java Script side of things happen. But inside that code, we’re going to call our backend proxy, which will really do the call to the validation. We’ll go over that next.
This is the call address validation method. It takes in the parameters that we sent in earlier from below. Then it makes an AJAX call, and processes the request. It processes the request against a Handler that we create, and that’s basically a backend script that’s going to allow us to hide our license key from being exposed to the outside world. It’s going to make a call to the API from there. It’s going to do the address validation. It’s going to process the response, and send it back to the AJAX method here. It’s going to land in either the success, or error sections here.
If there’s a response, and we have data coming back, and everything looks good, then we’re going to go into the success method. If not, we’re going to land in the error. With the error, we’re going to call the Handler again, but this time, we’re going to call the ValidateAddressBackup method instead. The only difference here, is that we’re calling the backup endpoint. Everything between the two endpoints is really the same, it’s just a backup server with the same data. Everything’s going to be the same, except, this is basically how we’re going to be handling our failover so that we can always guarantee a response from the service.
From there, we can still have a success or a fail. If we have a fail, then there’s more likely than not, a network error. Based on your process, you might be able to return more detail then show network error that I have here, but it really just depends on what you’re doing. If we’re successful, then again, we’ll call the success method. The AJAX method is going to call the Handler.aspx methods, and they’re going to basically be a single web form with nothing really on the markup page, except the basic stuff that gets prepopulated there. Really doesn’t matter, we’re not going to be using this part of it. We’re more interested in the Handler.aspx.cs page, the code behind for that page.
This is the page that’s going to be doing the request to the API. It’s going to be pulling in our key information from the Web.config file. Then it’s going to call out to the web service, and come back with a response, and then send that back to the Java Script that was calling us originally. To create the service references, you can go to References, and click Add Service Reference. In here you can fill in the URL of the address to the WSDL, and then name it. To know what URL to use here, you could just go to our website, and look at our docs. The documentation page is docs.serviceobjects.com. If you go there, you’ll have a list of all the services that we have. You’ll click on Address Validation. Once you get to Address Validation, you could scroll down a little bit, and find the WSDL.
This is the link to the trial WSDL. Just copy and paste that here, hit Go, and it finds the service. Here you can rename it however you’d like. I’ve already done this for our live, and backup endpoints, so let me just go over those with you really quick. What we’ve done already is created the AVI, and AVI Backup endpoints here. Right now, they’re actually both configured to look at this trial.serviceobjects.com endpoint. This is the main endpoint, and the backup endpoint. That one also is set to the trial.serviceobjects.com endpoint.
When you start out, you’re going to have your trial key. You’re going to set it up this way. But when you move to production, you’re going to come in here, and you can update this to ws.serviceobjects.com for your main endpoint. And then you’ll switch over to the backup endpoint, and you’ll switch trial over to wsbackup.serviceobjects.com. That way, you could hit the live, and backup endpoints, with the service reference.
Here in the Web.config file, you’re going to see a couple of things. Here we have appSetting key that we set for a value that we can pull in for the timeout, 5000 milliseconds, five seconds, and our license key for our service that we got in the trial signup for Address Validation – International. The rest of this is generated code based off of the WSDL that you created with the service reference earlier. There’s really not much going on in here, but the key part is that you have a license key outside of the application. We can change it on the fly, but it’s also something that gets pulled in, and it’s not seen by anyone who’s running your code, who’s running the form, who can easily look at your JavaScript or your code and see the underlying methods, the underlying codes. You won’t be able to see our key exposed this way.
Back in the Handler.aspx.cs file, we have the two methods, the ValidateAddressLive, and ValidateAddressBackup. They’re pretty much going to be doing the exact same thing, so we’re just going to go over one of them. The main point is that one of them is going to have the live endpoint, and the other one’s going to have the backup endpoint. Basically that’s really the only difference. Typically I would actually have this set into just one method, and maybe have another parameter here, but I just wanted to spread this out so that you could see that there is a difference, and one’s calling a main endpoint, and one’s calling a backup endpoint.
As I mentioned earlier, the live and backup endpoints are both pointed to the trial endpoint at this point. That’s what we’re going to keep doing here during our trial purposes, but when we switch to live, we’re going to switch our endpoints to the ws endpoint. Then for the backup, we’ll switch it to ws backup. Here we go. We’re going to start with this method. To be able to call it from the Java Script code, what we want to do is decorate the method with the web method attribute here. After that, we’re going to create the response object, and the service client object. From there we’re going to pull in our license key for the web service, and for the Address Validation – International API. Along with that, we’re going to pull back the 5000 millisecond timeout, the five second timeout.
After that, we create our client, and add the settings to it. Finally, we’re ready to call the endpoint with our parameters, with address one, two, we set a couple of these fields to empty strings, because we don’t need them in our cases. But depending on what country you’re dealing with, you may be pulling back address line one, two, three, four, five. So that’s what this is a placeholder for, is for additional address lines. We’re keeping it simple, and we’re just dealing with address lines one, and two. We’re going to cover the majority of situations this way anyways.
But those are there just in case you want to handle things a little bit differently. Then we have the Locality, AdministrativeArea, PostalCode, Country, and OutputLanguage, followed by the license Key. Since this is all on the backend server end, instead of the client, you’re going to be hiding the license key from anyone seeing it, and that’ll really protect your key from anybody being able to use it for any other purposes, other than what you’re intending here.
After the call to the service is made, the response is populated. If we have a null response, then we’ll just return an empty string, otherwise, we’re going to de-serialize the response into a JSON string, and return the JSON. The same exact same thing’s going to be happening here when, and if we need to make a call to the backup endpoint.
Here we are back in the CallAddressValidation method, where we called a Handler from the AJAX. Now we know what happens when the Handler is called. It basically calls the Address Validation – International API, processes it, and returns a result back to us. From there, we do the success, or the fail, the success, or error. In this case, we’re going to start by going through the success, and then we’ll go back over the error, or the failover later.
Going into the success, to get there, we make sure that the response object is not empty, so it has something to process. From there we get the JSON value out. It’s really just a JSON string at that point. Then we pass that over to the success method. Moving down to the success method, there’s really nothing too complicated here. What we’re doing is looking to see that the response is not undefined, and the response.AddressInfo object is not undefined as well. If we have those two things, we’re going to come in here, and we’re going to start building some string HTML output.
We’re going to use the string HTML output later on to inject back into class a div that we have on the main page. Let me see if I can find that. I might have it highlighted here already for us. This div, we’re going to try to populate that with the string HTML that we have in the JavaScript here. Moving back up, we’re going to be populating the HTML output with string HTML that we’re going to build in this method. We’re going to build it based off of comparing the inputs that were on the form, to the outputs of the results that we got from the API. That’s why you might really be wondering at this point why are we pulling back in the values that we had earlier, that we already passed and used to the address validation method?
Well, we’re pulling them back in so that we have these values locally, and that we can compare them to the output results from the service. We can show to the user what’s different between what we entered, and what the API found. Moving down … well first we have the inputs, these are the outputs pulled from the response object. Now we start building our HTML. We’re really just making our comparisons here, and figuring out how we want to display the output. Let’s just move to one of these ones here. Here we check to see if the outputLocality is not undefined. If we have something then, if it’s not equal to the input, then we’re going to put a “Bold” clasp, put “Bold” around the result, so that we can point out, or make it easy for the client to see, what is different, so they quickly make changes on their end, once they see the result.
We do that comparison for several of these fields. Based on what you’re doing, you’re going to want to probably do this section a lot different. This is just mainly a demonstration so you can see how we’re getting the elements out of the JSON, and how we’re comparing them to the inputs. You’ll have likely a different scenario, but this is how you could use it. As we move down here, the HTML is built. Then we inject it into the div. Back at the top of the success method, we demonstrated what happened if the response was not undefined, and the AddressInfo object was not undefined. Well, what happens if they are undefined?
Let’s go down and see what happens there. Well first we check to see if there is a response object that actually is defined, but has an error object that’s defined as well, and in particular, an error object with a TypeCode three. Well, if response is still undefined, we’re going to drop down here, and we’re just going to show the error. Otherwise, if we have the response code three, then we’re going to want to do a failover call. We’re only going to want do it once. We govern that with this count object that we increment once we get in here. That’ll force this to only ever happen once. Then we’ll call the failover method.
If we’ve already done it before, then we’re going to just drop down, and do the error response. One key thing that I want to point out here is that, even though we’ve made it into the success method, doesn’t mean we’re on our way to success guaranteed. There could be other problems along the way, like I just demonstrated with the else here, and what could have happened with the response. Success needs to be taken with a grain of salt. You might want to name it a little differently, so it’s a little more clear, but it’s not 100% success.
Now that we’ve gone over the success method popping out of the AJAX call here, well we should probably go over the error method when AJAX comes back with an error. When there’s an error, we’re just going to simply try our post to the other method, the ValidateAddressBackup method on the Handler. From there, it’s really, like I said earlier, going to do the exact same thing as the live, but call the backup endpoint, and run through the same steps. In here, again, we can have a success, or a fail, or a success and an error. If we get a success on the backup endpoint, then we’ll follow what we just went through with the success method, otherwise we’re going to show, at this point, it’s likely some sort of network error. We might, again, have some other information that you can add to this. You’ll do whatever you want there. We’re just showing a network error for now.
Earlier, as we went through the success method, and we realized that there’s an option when the address info or the response is undefined, we have this else here at the bottom. Well, I had mentioned the failover method here. The failover method, just to go into that briefly, it really mimics the same thing that the error did in the AJAX call, it just basically makes a second call to the other endpoint, to the backup endpoint, just in case there was a problem. It’s doing the exact same thing as earlier. You’ll see the exact same code here as you did there. You could pull this out into a method, and make sure that you only call this thing once since repeated, but here it is a demonstration just so it’s easy to see that you can do it this way.
Besides that, I think we’re pretty much wrapping up going over this code. There really isn’t much else on this file that’s complicated. Here’s a couple of methods that use jQuery to remove and add classes based on what comes back from the service, and what you want to display to the screen. It’s just basically checking in off of the classes, and then removing, or adding classes based off of the results. There’s nothing too big there.
The other important one here is this geolocate. This really helps with the auto-complete, where it pretty much does a bias to where … to a location. In this case, we have it set to a lat/long. What it does, is it looks for your current location. It gets the lat/long, and draws a radius around that location. It biases the results to that circle. When the form is created, if we look down here at the bottom, you’ll see that … where is it? Oh, here it is. When the field is focused on, we set the geolocate method. From there, that’s how we create the bias.
There you have it. That’s pretty much it. What we have left to do now is just give this a run, and see what we built. Everything loaded up properly, as expected. We have our drop-down menu with the countries. Let’s try our Service Objects address. 27 East … There it is, 27 East Cota Street. That really helps adding those kinds of addresses real quick. Let’s just do any address, how about … and this is obviously biased from where I’m located. I’m located in Santa Barbara.
Even though I have the country selected to United States, which is correct, it’s not picking any random place in the United States to start guessing. It’s basically picking where I’m sitting. That’s going to be an important detail for a lot of people in call-centers that are working locally, or if you’re in a call-center, and you change locations, you might want to give people an option to change their bias to a particular area, so they get results that come up quicker for the area that they’re located in.
Let’s pick this address here. Populates the fields here. Then we can click Validate. Then what comes back is the address that was … or that came back from the service, and the address that was entered. We can see that East was changed, Street was changed, and we have the plus-four added to the results. We still have some other details, but you know the service, it comes back with a lot of different details. I just gave you a rough, short look at what you can do. If you look at the API in the documentation page that I showed you earlier, there’s a lot of information there that will allow you to do many different things with the service. There’s a lot of different fields that come back that are useful.
In this case, someone could click on one of these, and either proceed with one of these addresses, or they can close, or try a different address, but that’s basically how the address suggestion application works. Thank you.
