Places UI Kit: A ready-to-use library that provides room for customization and low-code development. Try it out, and share yourinput on your UI Kit experience.

Address Validation

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();
Note: Read theguide on using TypeScript and Google Maps.

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();
Note: The JavaScript is compiled from the TypeScript snippet.

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.