libaddressinput: the address rules engine behind Android and Chromium

Two libraries, one shared data set

The libaddressinput project consists of two different libraries, one implemented in C++ and one implemented in Java for Android, and both use the same address metadata from Google's Address Data Service.

That split is the shape of the whole project, and it is unusual. A library that exists twice, in two languages, with a shared data source rather than a shared implementation, exists because the two consumers are different. The C++ library is in very portable C++11 and is used in address-related projects in Chromium. The Java library is written for use in Android and includes an Android UI address input widget ready for use, with only the UI parts tied to Android, so the non-UI code and tests can be run in Java SE and the rest of the library could easily be adapted to run in any Java environment.

The repository layout reflects that. There is a cpp directory, an android directory and a common directory, which is where the shared pieces live, plus externals for the third party code it vendors, testdata for the fixture data, and a Gradle build with a wrapper and a settings.gradle for the Java side.

So the data is the common asset and the code is two front ends onto it. That has a practical consequence for anyone adopting it: the behaviour of address validation is defined by the metadata, and the two implementations are different pieces of code that have to agree about it. The repository has a CONTRIBUTORS file, an AUTHORS file and a changelog-free but structured set of testdata, which is what a project like that needs to keep the two in step.

What the libraries actually do for a form

The functionality the readme names is specific and has two halves.

The first is telling an application what a correct address input form looks like for any country in the world. That is, the library can provide information about what input fields are required for a correct address input form for a given country. This is the part that surprises people who expect an address validator and get something else: the question is not is this address real, it is which fields does this country actually use, in what order, with which labels, and which are required.

The second is validation, where the library can validate an address to highlight input errors like missing required fields or invalid values.

Put together, the two give a form builder a per country schema and a checker for it. The field requirements come from real data rather than from a developer guessing, which matters because postal address formats differ more than most developers assume. The ordering of the fields is not universal, the labels are not universal, and the set of required fields is not universal either. A generic form with a single address line works for a minority of countries and produces a bad experience for the rest.

The metadata behind both halves is published by Google as address validation metadata, and the readme links both the metadata documentation and the Address Data Service itself, so the data can be inspected independently of the code.

For the Chromium case this is a browser feature rather than a library feature, since the browser has a built-in address form that follows the user's locale, and libaddressinput is one of the components under it. The same is true of Android, where the framework ships an address input widget. That is the clearest statement of what the library does well, because the two hardest consumers of postal formats in the world are shipping it.

The C++ side is a library, the Java side is a widget

The difference in how the two are meant to be consumed is worth spelling out, because it determines what you inherit when you take one.

The C++ library is described in very portable C++11, and it is used in address-related projects in Chromium, with the readme pointing at the third_party/libaddressinput path in the Chromium source tree. Portable C++11 is a deliberate constraint for a library that has to compile inside a browser engine and on whatever else people build with it, and it means the library does not require a modern toolchain to consume.

The Java library is a different proposition. It is written for use in Android and includes an Android UI address input widget ready for use. The qualification that only the UI parts are tied to Android is the important one, because it means you can take the validation and metadata handling without the widget, run it in Java SE, and adapt the rest to any Java environment.

So if you are writing an Android app and want a ready address form, the Java library gives you a widget you can drop in. If you are writing a server side service in Java that validates addresses, you take the non-UI parts. If you are writing in C++, you take the C++ library and provide your own UI.

That the C++ side is described first and called the library, while the Java side is called a library that also includes a widget, is a small hint about where the two efforts are concentrated. The readme's framing of the Java side as needing to be adaptable to other Java environments also suggests it was written with a wider audience in mind than Android alone, even though Android is the reason it exists.

Two licences, and the data is the one to watch

The licensing is stated in two sentences and the second one is the one that matters.

Source code licensed under the Apache 2.0. Data licensed under the CC-BY 4.0.

That split exists because the code is Google's and the metadata is derived from postal data that Google obtains and publishes under an attribution licence. For a commercial application, the practical requirement is that the data be attributed, and the CC-BY 4.0 obligation is not a coding matter but a documentation and display one.

The distribution mechanics follow from this. The metadata is not built into the libraries; it comes from the Address Data Service, and the readme points at the metadata documentation so a developer can see the format and the licensing before committing to the approach. The externals directory in the repository suggests the libraries vendor the parsing and validation code they depend on rather than requiring a system package, which is what a library that must build inside Chromium needs, and it also means you get whatever version the project pinned rather than a newer one with a different behaviour.

The source is Apache 2.0, which is permissive for a commercial product, and the project is hosted under the googlei18n organisation with a Travis build badge, so the continuous integration is Travis rather than GitHub Actions, which dates the setup.

The state of the project, and the question of the data lifecycle

The dates are the part to weigh, and they split into two different questions.

The last push to the repository was on 2026-05-15, and the repository publishes no GitHub releases at all. There is no version tag to pin, so a consumer is tracking a branch. For a library embedded in Chromium and in Android, that is unremarkable, because both platforms vendor the code and control the upgrade, but it is a real constraint for anyone using the C++ library directly.

The second question is the data, and the readme does not answer it. The metadata comes from Google's Address Data Service, and the library is a consumer of that data rather than its author. If the data is refreshed, the library's behaviour changes with it, and if the service changes shape, the library has to follow. A project with no releases and a last push five months ago can be perfectly healthy if the upstream data is what moves, and the metadata documentation is where you would look to find out.

What the project does offer is a place to ask questions. Using and developing libaddressinput is discussed on a mailing list, the libaddressinput-discuss group on Google Groups, and the readme points to it as the place for both.

So the honest summary is a mature, widely deployed library with a permissive source licence and a separately licensed data set, whose ongoing maintenance is mostly a question about the data rather than the code. For a team building a checkout form, the hard part was never the parsing, it was knowing what the rules were, and this project is where the rules are.

Editorial conclusion

Adopt libaddressinput if you are building a checkout, a shipping form or a signup form that has to accept postal addresses from more than one country, and you want the field requirements to come from real data rather than from a guess. Do not adopt it if you need an address that is validated against a postal database, since this validates structure and field values rather than deliverability. Before you commit, read the address validation metadata documentation, check the two licence terms separately, since the code is Apache 2.0 and the data is CC-BY 4.0, and decide early whether you want the C++ or the Java implementation.

Frequently asked questions

Official sources

1. google/libaddressinput on GitHub
2. Issues
3. License: Apache-2.0
4. README