Skip to main content
The SDK is on Maven Central. Make sure mavenCentral() is among your repositories, in settings.gradle.kts for a standard Android project:
Then add the dependency in your module’s build.gradle.kts:
Or with a version catalog, in gradle/libs.versions.toml:
The library needs minSdk 24 or higher. It brings its own UI, so the host app does not need Jetpack Compose, and the INTERNET and location permissions it declares merge into your manifest automatically.

Usage

In Compose, rememberLauncherForActivityResult(PostcodeWidgetContract()) does the same thing. Register the contract as a field, the way every activity result is registered, rather than inside a click handler. The registration is what Android calls back into after it recreates your activity, so it has to exist again by the time the result arrives. launch() opens the widget in its own activity: the identity screen (replaced by a confirm screen when prefilledIdentifier is set), saved postcodes, and the map-based discover flow. The callback receives the PostcodeSelection, or null if the user backed out. selection.toJson() produces exactly the wire shape every other SDK delivers.
Changed in 0.2.0. PostcodeWidget.show(context, config, onResult) is gone, replaced by the contract above. The callback show() took lived only in memory, so when Android killed the process the widget closed itself and the host was never told anything at all. A registered contract is restored with the activity, and the config travels in the intent, so the widget comes back and the answer still arrives.

Hosts that cannot register a contract

A React Native or Flutter bridge has no lifecycle point to register at. Build the intent yourself, start it for a result, and read the result back with the same contract:

Configuration

The SDK requires minSdk 24 and brings its own UI inside its own activity, so any Android app works. Hosts declare no extra permissions: INTERNET and location arrive via manifest merge, and the widget requests location permission itself for the “Get Postcode on Map” discover flow.

Requesting a postcode

Where discover finds nothing, the widget is a dead end by default. With allowPostcodeRequest = true it instead offers to request one: the user describes the place, picks what is there, and gets a temporary postcode back immediately — a TP-… code that stands in for the real one until the building is surveyed. A temporary code is not a postcode in the scheme:
  • segments and names are all null, since it has no state, LGA, district, area or unit
  • temporary is true on the selection, and absent on an ordinary one
  • looking it up through /v1/lookup answers with the real postcode once one is assigned, so a stored TP-… keeps working
That is why this is off by default. A host app that has not handled the temporary case would fail its own validation on a TP-… code, or store something it cannot read back. Turn it on once you have. The form asks for an address or description, the building type, what is there and an optional landmark, using the same vocabulary as the NIPOST app, so a widget request reads the same to whoever reviews it. The user requests for their own location or taps the map to pick the building they mean. One request per session: a second is refused and the widget shows the code the session already has.
Available on Android from 0.2.0. The other SDKs do not offer it yet.