Loccodes are Maiaddy's address primitive, and they show up in nearly every Maimaps response: on search results, on reverse-geocode lookups, on individual route steps. This guide explains what they are and how to use them.

The one thing to understand

That design is deliberate. In much of Nigeria there is no reliable house-number system, so the street is the addressable unit. A loccode is precise enough to navigate to and coarse enough to actually exist.

The format

A loccode is four characters, a space, then three: FC2F 3KN. Anything else is rejected with a 400 INVALID_PARAMS before it reaches the map engine.

There is a small wrinkle in the response. Resolve a loccode and you get both:

{
  "loccode": "FC2F3KN",
  "formatted": "FC2F 3KN"
}

loccode is the unspaced key. formatted is the display form. Render formatted, store either, and always send the spaced form in requests (URL encode the space as %20).

Resolve a loccode

const loccode = await client.loccode.resolve("FC2F 3KN");

loccode.streetName;          // "Moshood Abiola Way"
loccode.highwayType;         // "primary"
loccode.streetLength;        // 1840.2  (meters)
loccode.state;               // "FCT"
loccode.lga;                 // "Abuja Municipal"
loccode.representativePoint; // { latitude: 9.0345, longitude: 7.4901 }
loccode.geometry;            // GeoJSON LineString for the whole street

Note streetLength is in meters, like every other distance in the API except search's distanceKm.

An unknown or malformed code returns 404 NOT_FOUND, which the SDKs surface as a MaimapsError with httpStatus: 404.

Find the nearest loccode

The inverse, and the fastest way to turn a raw GPS fix into a Maiaddy address:

const nearest = await client.loccode.nearest({
  latitude: 9.0579,
  longitude: 7.4951,
});

nearest.formatted;  // "FC2F 3KN"

It returns the same shape as resolve. Outside Nigeria, or outside coverage, you get a 404.

Route to a loccode

Either endpoint of a route can be a loccode instead of a coordinate pair. Use the POST form, which the SDKs expose as routeAdvanced:

const trip = await client.routeAdvanced({
  originLoccode: "FC2F 3KN",
  destLoccode: "FC1A 9PQ",
  mode: "drive",
});

Both ends resolve to their street midpoints, and the route runs between those. If a loccode cannot be resolved, you get a 502 ENGINE_UNAVAILABLE, which lumps "the map engine is down" together with "that loccode did not resolve." It is not a distinction the API currently makes for you.

Loccodes on route steps

Every step in a route response carries the loccode of the street it follows:

{
  "distance": 412.0,
  "name": "Moshood Abiola Way",
  "loccode": "FC2F 3KN",
  "maneuver": { "type": "depart", "modifier": "straight" }
}

This is what makes turn-by-turn directions speakable in local terms rather than purely as street names.

In Flutter

The Dart client mirrors the same two calls, and LoccodeResult adds cache helpers so you can persist a resolved loccode without hand-rolling serialization:

final loccode = await Maimaps.instance.loccode.resolve('FC2F 3KN');

debugPrint(loccode.displayAddress);
final midpoint = loccode.representativePoint;  // LatLng?

// Cache it
final json = loccode.toJsonString();
final restored = LoccodeResult.fromJsonString(json);

What's next

Handling errors and quotas covers the 404 and 502 cases above properly.
The Maimaps API reference documents both loccode endpoints in full.