Address Validation Stay organized with collections Save and categorize content based on your preferences.
Use this demo to try the Address Validation API using any address from asupported region. The demo takes address components as input, and displays thevalidation response below. To parse an unstructured address, enter the entireaddress in theStreet Address 1 field. Select example addresses from thedrop-down at the top of the form.
Read thedocumentation.
TypeScript
// DOM RefsconstaddressForm=document.getElementById('address-form');constvalidateButton=document.getElementById('validate-button');constclearFormButton=document.getElementById('clear-form-button');constresultDisplay=document.getElementById('result-display');constloadingText=document.getElementById('loading-text');// Input field refsconststreetAddress1Input=document.getElementById('street-address-1')asHTMLInputElement;conststreetAddress2Input=document.getElementById('street-address-2')asHTMLInputElement;constcityInput=document.getElementById('city')asHTMLInputElement;conststateInput=document.getElementById('state')asHTMLInputElement;constzipCodeInput=document.getElementById('zip-code')asHTMLInputElement;constregionSelect=document.getElementById('region-select')asHTMLSelectElement;constexampleSelect=document.getElementById('example-select')asHTMLSelectElement;// Core Initializationasyncfunctioninit(){// Load the Address Validation library.awaitgoogle.maps.importLibrary('addressValidation');// Set event listenersaddressForm!.addEventListener('submit',handleValidationSubmit);exampleSelect!.addEventListener('change',handleExampleSelectChange);clearFormButton!.addEventListener('click',handleClearForm);}// Validation HandlerasyncfunctionhandleValidationSubmit(event){event.preventDefault();// Prevent default form submissionresultDisplay!.textContent='Validating...';// Clear previous results// Validate the addresstry{//prettier-ignore//@ts-ignoreconstresult=awaitgoogle.maps.addressValidation.AddressValidation.fetchAddressValidation({address:{regionCode:regionSelect!.value.trim(),languageCode:'en',addressLines:[streetAddress1Input!.value.trim(),streetAddress2Input!.value.trim(),].filter((line)=>line),// Filter out empty lineslocality:cityInput!.value.trim(),administrativeArea:stateInput!.value.trim(),postalCode:zipCodeInput!.value.trim(),},});resultDisplay!.textContent='Verdict summary\n================\n'+`Formatted address:${result.address.formattedAddress}\n`+`Entered:${result.verdict.inputGranularity}\n`+`Validated:${result.verdict.validationGranularity}\n`+`Geocoded:${result.verdict.geocodeGranularity}\n`+`Possible next action:${result.verdict.possibleNextAction}\n\n`+`${getVerdictMessage(result.verdict,'addressComplete')}\n`+`${getVerdictMessage(result.verdict,'hasUnconfirmedComponents')}\n`+`${getVerdictMessage(result.verdict,'hasInferredComponents')}\n`+`${getVerdictMessage(result.verdict,'hasReplacedComponents')}\n\n`+`Raw JSON response\n=================\n`+JSON.stringify(result,null,' ');}catch(error){console.error('Validation failed:',error);if(errorinstanceofError){resultDisplay!.textContent=`Error:${error.message}`;}}}// Verdict messagesconstverdictMessages={addressComplete:{trueMessage:'- The API found no unresolved, unexpected, or missing address elements.',falseMessage:'- At least one address element is unresolved, unexpected, or missing.',},hasUnconfirmedComponents:{trueMessage:"- The API can't confirm at least one address component.",falseMessage:'- The API confirmed all address components.',},hasInferredComponents:{trueMessage:'- The API inferred (added) at least one address component.',falseMessage:'- The API did not infer (add) any address components.',},hasReplacedComponents:{trueMessage:'- The API replaced at least one address component.',falseMessage:'- The API did not replace any address components.',},};// Helper function to get the verdict message for a given verdict keyfunctiongetVerdictMessage(verdict,key){if(!verdict||!verdictMessages[key])return'Unknown';returnverdict[key]?verdictMessages[key].trueMessage:verdictMessages[key].falseMessage;}// Handler for Dropdown ChangefunctionhandleExampleSelectChange(event){constselectedValue=event.target.value;if(selectedValue &&examples[selectedValue]){populateAddressFields(examples[selectedValue]);}elseif(!selectedValue){populateAddressFields(null);// Pass null to clear fields}}// Clear Form HandlerfunctionhandleClearForm(){streetAddress1Input!.value='';streetAddress2Input!.value='';cityInput!.value='';stateInput!.value='';zipCodeInput!.value='';regionSelect!.value='';exampleSelect!.value='';resultDisplay!.textContent='Result will appear here...';console.log('Cleared form');}// Example Address Dataconstexamples={google:{streetAddress1:'1600 Amphitheatre Parkway',streetAddress2:'',// Explicitly emptycity:'Mountain View',state:'CA',zipCode:'94043',region:'US',},nonExistentSubpremise:{streetAddress1:'2930 Pearl St.',streetAddress2:'Suite 100',city:'Boulder',state:'CO',zipCode:'',// Explicitly emptyregion:'US',},missingSubpremise:{streetAddress1:'500 West 2nd Street',streetAddress2:null,// Can use null or undefined toocity:'Austin',state:'TX',zipCode:'78701',region:'US',},misspelledLocality:{streetAddress1:'1600 Amphitheatre Pkwy',streetAddress2:'',city:'Montan View',state:'CA',zipCode:'94043',region:'US',},missingLocality:{streetAddress1:'Brandschenkestrasse 110 8002',streetAddress2:'',city:'',state:'',zipCode:'',region:'',},usPoBox:{streetAddress1:'PO Box 1108',streetAddress2:'',city:'Sterling',state:'VA',zipCode:'20166-1108',region:'US',},};// Helper function to populate form fields with example address datafunctionpopulateAddressFields(exampleAddress){if(!exampleAddress){console.warn('No example address data provided.');return;}// Get values from example, providing empty string as defaultstreetAddress1Input!.value=exampleAddress.streetAddress1||'';streetAddress2Input!.value=exampleAddress.streetAddress2||'';cityInput!.value=exampleAddress.city||'';stateInput!.value=exampleAddress.state||'';zipCodeInput!.value=exampleAddress.zipCode||'';regionSelect!.value=exampleAddress.region||'';// Clear previous results and errorsresultDisplay!.textContent='Result will appear here...';console.log('Populated fields with example: ',exampleAddress);}init();
JavaScript
// DOM RefsconstaddressForm=document.getElementById('address-form');constvalidateButton=document.getElementById('validate-button');constclearFormButton=document.getElementById('clear-form-button');constresultDisplay=document.getElementById('result-display');constloadingText=document.getElementById('loading-text');// Input field refsconststreetAddress1Input=document.getElementById('street-address-1');conststreetAddress2Input=document.getElementById('street-address-2');constcityInput=document.getElementById('city');conststateInput=document.getElementById('state');constzipCodeInput=document.getElementById('zip-code');constregionSelect=document.getElementById('region-select');constexampleSelect=document.getElementById('example-select');// Core Initializationasyncfunctioninit(){// Load the Address Validation library.awaitgoogle.maps.importLibrary('addressValidation');// Set event listenersaddressForm.addEventListener('submit',handleValidationSubmit);exampleSelect.addEventListener('change',handleExampleSelectChange);clearFormButton.addEventListener('click',handleClearForm);}// Validation HandlerasyncfunctionhandleValidationSubmit(event){event.preventDefault();// Prevent default form submissionresultDisplay.textContent='Validating...';// Clear previous results// Validate the addresstry{//prettier-ignore//@ts-ignoreconstresult=awaitgoogle.maps.addressValidation.AddressValidation.fetchAddressValidation({address:{regionCode:regionSelect.value.trim(),languageCode:'en',addressLines:[streetAddress1Input.value.trim(),streetAddress2Input.value.trim(),].filter((line)=>line),// Filter out empty lineslocality:cityInput.value.trim(),administrativeArea:stateInput.value.trim(),postalCode:zipCodeInput.value.trim(),},});resultDisplay.textContent='Verdict summary\n================\n'+`Formatted address:${result.address.formattedAddress}\n`+`Entered:${result.verdict.inputGranularity}\n`+`Validated:${result.verdict.validationGranularity}\n`+`Geocoded:${result.verdict.geocodeGranularity}\n`+`Possible next action:${result.verdict.possibleNextAction}\n\n`+`${getVerdictMessage(result.verdict,'addressComplete')}\n`+`${getVerdictMessage(result.verdict,'hasUnconfirmedComponents')}\n`+`${getVerdictMessage(result.verdict,'hasInferredComponents')}\n`+`${getVerdictMessage(result.verdict,'hasReplacedComponents')}\n\n`+`Raw JSON response\n=================\n`+JSON.stringify(result,null,' ');}catch(error){console.error('Validation failed:',error);if(errorinstanceofError){resultDisplay.textContent=`Error:${error.message}`;}}}// Verdict messagesconstverdictMessages={addressComplete:{trueMessage:'- The API found no unresolved, unexpected, or missing address elements.',falseMessage:'- At least one address element is unresolved, unexpected, or missing.',},hasUnconfirmedComponents:{trueMessage:"- The API can't confirm at least one address component.",falseMessage:'- The API confirmed all address components.',},hasInferredComponents:{trueMessage:'- The API inferred (added) at least one address component.',falseMessage:'- The API did not infer (add) any address components.',},hasReplacedComponents:{trueMessage:'- The API replaced at least one address component.',falseMessage:'- The API did not replace any address components.',},};// Helper function to get the verdict message for a given verdict keyfunctiongetVerdictMessage(verdict,key){if(!verdict||!verdictMessages[key])return'Unknown';returnverdict[key]?verdictMessages[key].trueMessage:verdictMessages[key].falseMessage;}// Handler for Dropdown ChangefunctionhandleExampleSelectChange(event){constselectedValue=event.target.value;if(selectedValue &&examples[selectedValue]){populateAddressFields(examples[selectedValue]);}elseif(!selectedValue){populateAddressFields(null);// Pass null to clear fields}}// Clear Form HandlerfunctionhandleClearForm(){streetAddress1Input.value='';streetAddress2Input.value='';cityInput.value='';stateInput.value='';zipCodeInput.value='';regionSelect.value='';exampleSelect.value='';resultDisplay.textContent='Result will appear here...';console.log('Cleared form');}// Example Address Dataconstexamples={google:{streetAddress1:'1600 Amphitheatre Parkway',streetAddress2:'',// Explicitly emptycity:'Mountain View',state:'CA',zipCode:'94043',region:'US',},nonExistentSubpremise:{streetAddress1:'2930 Pearl St.',streetAddress2:'Suite 100',city:'Boulder',state:'CO',zipCode:'',// Explicitly emptyregion:'US',},missingSubpremise:{streetAddress1:'500 West 2nd Street',streetAddress2:null,// Can use null or undefined toocity:'Austin',state:'TX',zipCode:'78701',region:'US',},misspelledLocality:{streetAddress1:'1600 Amphitheatre Pkwy',streetAddress2:'',city:'Montan View',state:'CA',zipCode:'94043',region:'US',},missingLocality:{streetAddress1:'Brandschenkestrasse 110 8002',streetAddress2:'',city:'',state:'',zipCode:'',region:'',},usPoBox:{streetAddress1:'PO Box 1108',streetAddress2:'',city:'Sterling',state:'VA',zipCode:'20166-1108',region:'US',},};// Helper function to populate form fields with example address datafunctionpopulateAddressFields(exampleAddress){if(!exampleAddress){console.warn('No example address data provided.');return;}// Get values from example, providing empty string as defaultstreetAddress1Input.value=exampleAddress.streetAddress1||'';streetAddress2Input.value=exampleAddress.streetAddress2||'';cityInput.value=exampleAddress.city||'';stateInput.value=exampleAddress.state||'';zipCodeInput.value=exampleAddress.zipCode||'';regionSelect.value=exampleAddress.region||'';// Clear previous results and errorsresultDisplay.textContent='Result will appear here...';console.log('Populated fields with example: ',exampleAddress);}init();
CSS
body,html{height:100%;margin:0;padding:0;overflow:hidden;font-family:'Google Sans',sans-serif;font-size:20px;color:#333;}#sidebar{width:800px;max-width:calc(100%-2rem);background-color:#fff;border-color:#9ca3af;border-style:solid;border-radius:0.5rem;box-shadow:04px6px-1pxrgba(0,0,0,0.1),02px4px-1pxrgba(0,0,0,0.06);display:flex;flex-direction:column;overflow:hidden;max-height:calc(100%-2rem);}.sidebar-header{padding:0.75rem;border-bottom:1pxsolid#e5e7eb;flex-shrink:0;}.sidebar-headerh2{margin:0;font-size:1.125rem;font-weight:600;color:#1f2937;}.sidebar-content{padding:0.75rem;overflow-y:auto;flex-grow:1;}.sidebar-content::-webkit-scrollbar{width:6px;}.sidebar-content::-webkit-scrollbar-thumb{background-color:rgba(0,0,0,0.2);border-radius:3px;}#address-form >div{margin-bottom:0.75rem;}#address-form >button{margin-top:1rem;}label{display:block;font-size:0.75rem;font-weight:500;color:#4b5563;margin-bottom:0.25rem;}input[type='text']{width:100%;padding:0.5rem0.75rem;font-size:0.875rem;border:1pxsolid#d1d5db;border-radius:0.375rem;box-sizing:border-box;transition:border-color0.15sease-in-out,box-shadow0.15sease-in-out;}input[type='text']:focus{outline:0;border-color:#2563eb;box-shadow:0001px#2563eb;}.form-grid-triple{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:0.75rem;}@media(max-width:400px){.form-grid-triple{grid-template-columns:1fr;}}button{display:inline-block;margin-right:0.5rem;width:auto;padding:0.6rem0.75rem;font-size:0.875rem;font-weight:500;color:#fff;background-color:#2563eb;border:none;border-radius:0.375rem;cursor:pointer;transition:background-color0.15sease-in-out;text-align:center;}button:hover{background-color:#1d4ed8;}#loading-indicator{margin-top:0.5rem;font-size:0.75rem;color:#2563eb;font-style:italic;display:none;align-items:center;gap:0.5rem;}.spinner{width:1em;height:1em;border:2pxsolidcurrentColor;border-right-color:transparent;border-radius:50%;animation:spin1slinearinfinite;display:inline-block;}@keyframesspin{to{transform:rotate(360deg);}}#error-message{margin-top:0.5rem;font-size:0.75rem;color:#dc2626;font-weight:500;display:none;}#result-container{margin-top:1rem;border-top:1pxsolid#e5e7eb;padding-top:0.75rem;}#result-display{font-family:Consolas,Monaco,'Andale Mono','Ubuntu Mono',monospace;font-size:0.75rem;background-color:#f3f4f6;padding:0.5rem;border-radius:0.25rem;overflow-x:auto;white-space:pre;height:12rem;border:1pxsolid#e5e7eb;}@media(max-width:767px){#sidebar{width:auto;max-width:100%;margin:0;max-height:70vh;border-radius:0;border-top-left-radius:0.5rem;border-top-right-radius:0.5rem;border-top:1pxsolid#d1d5db;box-shadow:0-4px6px-1pxrgba(0,0,0,0.1),0-2px4px-1pxrgba(0,0,0,0.06);}}.form-select{display:block;width:100%;padding:0.5rem2.5rem0.5rem0.75rem;font-size:0.875rem;font-weight:400;line-height:1.5;color:#333;background-color:#fff;background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23343a40' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M2 5l6 6 6-6'/%3e%3c/svg%3e");background-repeat:no-repeat;background-position:right0.75remcenter;background-size:16px12px;border:1pxsolid#d1d5db;border-radius:0.375rem;appearance:none;transition:border-color0.15sease-in-out,box-shadow0.15sease-in-out;cursor:pointer;}.form-select:focus{border-color:#2563eb;outline:0;box-shadow:0001px#2563eb;}.form-selectoption[disabled]{color:#9ca3af;}
HTML
<html> <head> <title>Address Validation</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <!-- Address Validation Form Container --> <div> <!-- Header --> <div> <h2>Address Validation</h2> </div> <!-- Content: Address Form --> <form autocomplete="off"> <!-- Example Dropdown Section --> <div > <label for="example-select" >Load Example Address:</label > <select name="exampleSelect" > <option value="" selected disabled> -- Select an Example -- </option> <option value="google">Valid Address</option> <option value="nonExistentSubpremise"> Non-existent Subpremise </option> <option value="missingSubpremise"> Missing Subpremise </option> <option value="misspelledLocality"> Misspelled Locality </option> <option value="missingLocality"> Missing Locality </option> <option value="usPoBox">US PO Box</option> </select> </div> <div> <label for="street-address-1">Street Address 1</label> <input name="streetAddress1" type="text" placeholder="e.g., 1600 Amphitheatre Parkway" /> </div> <div> <label for="street-address-2" >Street Address 2 (Optional)</label > <input name="streetAddress2" type="text" placeholder="e.g., Suite 100" /> </div> <!-- Use a div with grid class for City/State/ZIP layout --> <div> <div> <label for="city">City</label> <input name="city" type="text" placeholder="e.g., Mountain View" /> </div> <div> <label for="state">State or territory</label> <input name="state" type="text" placeholder="e.g., CA" /> </div> <div> <label for="zip-code">ZIP Code</label> <input name="zipCode" type="text" placeholder="e.g., 94043" /> </div> </div> <div> <div> <label for="region-select">Region</label> <select name="regionSelect" > <option value="AR">Argentina</option> <option value="AU">Australia</option> <option value="AT">Austria</option> <option value="BE">Belgium</option> <option value="BR">Brazil</option> <option value="BG">Bulgaria</option> <option value="CA">Canada</option> <option value="CL">Chile</option> <option value="CO">Colombia</option> <option value="HR">Croatia</option> <option value="CZ">Czechia</option> <option value="DK">Denmark</option> <option value="EE">Estonia</option> <option value="FI">Finland</option> <option value="FR">France</option> <option value="DE">Germany</option> <option value="HU">Hungary</option> <option value="IN">India</option> <option value="IE">Ireland</option> <option value="IT">Italy</option> <option value="JP">Japan</option> <option value="LV">Latvia</option> <option value="LT">Lithuania</option> <option value="LU">Luxembourg</option> <option value="MY">Malaysia</option> <option value="MX">Mexico</option> <option value="NL">Netherlands</option> <option value="NO">Norway</option> <option value="NZ">New Zealand</option> <option value="PL">Poland</option> <option value="PT">Portugal</option> <option value="PR">Puerto Rico</option> <option value="SG">Singapore</option> <option value="SK">Slovakia</option> <option value="SI">Slovenia</option> <option value="ES">Spain</option> <option value="SE">Sweden</option> <option value="CH">Switzerland</option> <option value="GB">United Kingdom</option> <option value="US" selected>United States</option> <option value="">Unknown</option> </select> </div> </div> <button type="submit"> Validate Address </button> <button type="button" event="handleClearForm"> Clear Form </button> <!-- Result Display Area --> <div> <label for="result-display" >Validation Result (formatted address and JSON)</label > <pre>Result will appear here...</pre> </div> </form> </div> <!-- prettier-ignore --> <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))}) ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script> </body></html>Try Sample
Clone Sample
Git and Node.js are required to run this sample locally. Follow theseinstructionsto install Node.js and NPM. The following commands clone, install dependencies and start the sample application.
gitclonehttps://github.com/googlemaps-samples/js-api-samples.gitcdsamples/address-validationnpminpmstart
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-11 UTC.