Secondary address unit designators

[Minh_Nguyen (Minh Nguyễn)]

How should we tag secondary address unit designators, if at all?

Background

In a typical building complex (apartment building, duplex, office building, strip mall, etc.), each building unit is assigned a unique number or letter, which is signposted and appears in the delivery address line of any incoming mail. The complex will have its own convention for referring to the number or letter with a word preceding it, such as “unit”, “suite”, or “apartment”.

The USPS calls these words secondary address identifiers or secondary address unit designators. They’ve approved 25 unit designators, and others exist informally at sites that operate their own mailstops. They require the designator and in some cases will reject mail that omits it or shortens it to something generic like “#”.

Each complex tends to use a different designator, or a mix of them, and they aren’t really interchangeable. Less commonly, a given address can have multiple secondary address numbers and multiple secondary address unit designators. For example, this insurance agent usually gives her address as “3350 Scott Blvd. Bldg. 12-01”. She shares the building with another business that goes by “Unit 1202”. The landlord signposts their addresses like “Bldg. 12, Unit 1”. Business owners tend to use the shortened form to avoid headaches when filling out forms that only accept a single unit number.

Problem

For the longest time, we’ve recommended setting addr:unit=* to just the number or letter, omitting the designator. Most address and POI imports have followed this guidance, completely dropping any information about designators. A clean number or letter conveniently allows rendered maps to label individual units without any postprocessing, as seen in OSM Carto and the map styles built into editors. After all, if every addr:unit=* in a building includes a word like “Suite”, the map would get cluttered with repetitive “Suite” labels in that spot:

Possible solutions

There’s always been a lingering question about how else to tag the unit designator. It seems unsatisfying to simply drop information that apparently does matter for real-world addressing purposes. There are currently a few different approaches in the wild, none of them predominating yet:

Freeform addr:unit=*

Some mappers have included the designator in addr:unit=* anyways, figuring that avoiding dataloss is more important than mapping for the renderer. Across the U.S., about 24,000 occurrences of addr:unit=* contain one of the seven most common unit designators:

Maybe keeping the whole secondary address together like this could theoretically facilitate geocoding, but geocoders universally ignore unit numbers at the moment, even in user input.

Single key for designator

In Augusta County and Lynchburg, Virginia, @pmfox and @OptikalCrow went with addr:unit:label=*. This keeps addr:unit=* simple for renderers but avoids dataloss, as long as the address has only one secondary address.

One key per designator

In the New York State address import, @dead10ck isolated the numbers but distinguished the designators by setting several different subkeys:

NYS GIS SAM	OSM
Building	addr:housename=*
Floor	addr:floor=*
Room	addr:door=*
Unit	addr:unit=*

The New York approach also isolates a number or letter for renderers to label while allowing for combinations of multiple secondary addresses. However, since the order can vary from site to site, these addresses would probably need addr:full=* to ensure that data consumers use the secondary addresses in the correct order.

NYS GIS was only tracking a few of the designators in the first place, not even all of the common ones. Only a few of the 25 approved unit designators correspond to subkeys that are well-documented or well-supported in software, likely because other countries’ addressing systems don’t consider components like “floor” to be unit designators at all. Another wrinkle is that some common unit designators like “Bsmt.” and “Rear” may or may not come with a number. Would we set addr:basement=yes and expect renderers to avoid labeling a literal “yes”?

Does this community have a preference for one of these approaches, or the status quo? Have I missed any other approaches? If we can align on a tagging scheme for unit designators, we can start thinking about backfilling the designators in some of the large imports that originally dropped them.

[SD_Mapman (Miles)]

@Minh_Nguyen

Single key for designator

In Augusta County and Lynchburg, Virginia, @pmfox and @OptikalCrow went with addr:unit:label=*. This keeps addr:unit=* simple for renderers but avoids dataloss, as long as the address has only one secondary address.

I support this approach, and have updated Spearfish SD to match (granted we only had four of these).

@Minh_Nguyen

They require the designator and in some cases will reject mail that omits it or shortens it to something generic like “#”.

When I lived in a townhome, the designator was “Unit”, which I thought was stupid so I used “#” whenever I could. Didn’t have any problems getting my mail, but maybe SD is less picky than other parts of the country.

[AntiCompositeNumber]

addr:unit:label is probably the better way way to go, and internationalizes better. Most addresses have at most one secondary unit designator for mailing purposes. These addresses may include a building number for navigation purposes though, and it might be worth getting agreement on how to best represent that whether it is required for the mailing address or not.

I would also note that the designators like “Upper” and “Rear” should be placed in addr:unit if they don’t have a number.

Is it better to spell out the designators (as would be standard OSM practice) or use the standard abbreviations (which is what people see and use most of the time)?

[citrula]

The major problem I see with the addr:unit:label scheme is that it doesn’t support multiple secondary unit designators.

To reuse my example from the last time this came up in the OSMUS Slack:
How would an address like “1 Main Street, Building A, Unit 100), be represented? The status quo is to concatenate them into some sort of recognizable sequence, like addr:unit=A100. I’m really not a fan of the namespaced designators, but it is able to solve this problem, with the exception of ordering like you mentioned.

I’ve attempted to look around for more detailed guidance from the USPS website about this several times in the past, and never found much clarity. In fact, none of their examples even indicate that several designators are possible, despite the fact that they seem to appear quite frequently (from my outsider perspective).

[Minh_Nguyen (Minh Nguyễn)]

@SD_Mapman

@Minh_Nguyen

They require the designator and in some cases will reject mail that omits it or shortens it to something generic like “#”.

When I lived in a townhome, the designator was “Unit”, which I thought was stupid so I used “#” whenever I could. Didn’t have any problems getting my mail, but maybe SD is less picky than other parts of the country.

“#” is used for the designator blank, unable to determine. You might get away with it but aren’t guaranteed to, sort of like leaving off the “St.” at the end of “Main St.”^[1] The addressing standards also warn against using “#” on some kinds of addresses:

Use of the pound sign might be prohibited when using a Commercial Mail Receiving Agency (CMRA) address with Private Mail Box (PMB) information.

This is a reference to shops like The UPS Store that rent out private mailboxes, which leads me to think other private arrangements, such as university mailstops, might also be affected.

@AntiCompositeNumber

Is it better to spell out the designators (as would be standard OSM practice) or use the standard abbreviations (which is what people see and use most of the time)?

If it’s in a tag value, then I think we should spell it out for consistency with directional prefixes and street suffixes in addr:street=*. If it’s in a tag key, I’d favor spelling it out too, in order to reduce the likelihood of conflicts with other unrelated tagging schemes. But as the New York import shows, the addr:*=* subkey doesn’t have to literally match the designator as long as there’s a one-to-one correspondence.

---

1. Don’t try that with “Peachtree” in Atlanta. ↩︎

[eddp (Edd)]

@citrula

How would an address like “1 Main Street, Building A, Unit 100), be represented? The status quo is to concatenate them into some sort of recognizable sequence, like addr:unit=A100.

I don’t think this is a “solvable” problem in the grander scheme. OSM has a standard for it with Multiple Values, but even when all the nodes/areas with e.g. addr:unit=A100 were updated to addr:unit=A;100 + addr:unit:label=Building;Unit, it would need a lot of coordination with consumers.

Without doing a multiple value solution, I think you’d have to do a new tags to solve this without simply providing addr:full which documentation suggests is preferred. Something along the lines of addr:tertiary/addr:quaternary/… with a note that addr:unit should be considered for the secondary address value and then we could have addr:unit:label/addr:tertiary:label/addr:quaternary:label/… to define how that should be built. However that still doesn’t fix the immediate issue with addresses labeled currently as addr:unit=A100 which brings us back to addr:full for anything that isn’t a primary number and a secondary/unit number + label as addr:unit describes.

I personally think addr:unit:label is a good solution that isn’t a breaking change (full text, allow consumers to shorten if required), but you won’t get away from addr:full for properly describing nested unit designators.

[Minh_Nguyen (Minh Nguyễn)]

@eddp

OSM has a standard for it with Multiple Values, but even when all the nodes/areas with e.g. addr:unit=A100 were updated to addr:unit=A;100 + addr:unit:label=Building;Unit, it would need a lot of coordination with consumers.

There are already plenty of semicolon-delimited value lists and ranges in addr:unit=*, for example where a shop occupies two adjacent storefronts in a strip mall or two floors of a building. These addresses have unit designators too. Repurposing the semicolon syntax for these double-barreled addresses would create a lot of ambiguity and confusion.

[Baloo_Uriza]

Is the specific form of unit ever relevant?

I ask because after extensive review, the USPS decided about 20 years ago that, no, it’s not. So 801 N Mingo Rd E #105 maps to RV space 105 at Mingo RV Park, and 1 Williams Center #700 would be suite 700 in Tulsa’s tallest building. So specifying that one’s a suite and one’s a space just adds irrelevant information.

So, at least it’s irrelevant in the US. Is there anywhere it is relevant?

[Minh_Nguyen (Minh Nguyễn)]

@Baloo_Uriza

I ask because after extensive review, the USPS decided about 20 years ago that, no, it’s not.

Interesting, that contradicts the rather limited documentation that I’ve found from the USPS, which uses “#” as a placeholder for an unknown designator and warns against using it in some cases. Do you know where we can find out more about that review?

Basically, if we tag just addr:unit=123 and nothing else, a data consumer that wants to format the address (say, in a POI detail sheet) would only be able to format the secondary address as “#123”, but not as “Suite” or “Unit” without making assumptions based on the building type.

Even if this is purely an idiosyncratic preference that doesn’t affect mail delivery at all, the idiosyncrasy isn’t recorded anywhere. Whereas we often do record businesses’ preferred city names in addr:city=* instead of canonicalizing them to the USPS preferred city name.

[Minh_Nguyen (Minh Nguyễn)]

To answer a question in Slack: it’s hard to say how many primary addresses correspond to secondary addresses that use more than one secondary designator, since we’ve generally been omitting that information in OSM. But of the relatively few cases where mappers have happened to stuff designators in addr:unit=*, 79 buildings have a mix of designators. For example, 300 Church Street in Staunton, Virginia, has both a Building B and a Suite 201, 700 Main Street in Buffalo has both a Floor 4 and a Suite 200, and 200 Varick Street in Manhattan has both a Room 1000 and a Front B. Based on the even less common addr:unit:label=* scheme, there are four such buildings.

[Baloo_Uriza]

@Minh_Nguyen

Do you know where we can find out more about that review?

I’ve been looking for that on and off all morning but the USPS website’s been pretty jank for about a decade now (thanks to certain antiamerican elements we’re all fighting with right now). I mostly remember getting a postcard from the USPS saying “apt” is no longer part of my address because they weren’t doing that anymore when the change happened, I stopped doing it, forms stopped asking for it, and I’ve yet to encounter an ambiguous case since.

[OptikalCrow]

For the record (as I was handling the import here), 198 South Main Street in Amherst, VA (a Suite-labeled building) only shows up in that query as it shares nodes with the building next to it, which uses the Apartment label. The others in that second query appear to be office buildings with artifacts from the Virginia address dataset using inconsistent labeling and should probably be checked on the ground or with a USPS dataset. I can see genuine cases for “Apartment” and “Suite” to be used in the same building for mixed-use commercial with residential units on the higher floors.

One of the conflicts I do see is that the addr:unit:label scheme does not play well when multiple units are represented by a single node. It is my understanding to shift to the addr:flats key to represent a range of unit numbers but I’ve never been a fan of this key as it seems to serve the exact same purpose as addr:unit but only to allow multiple addresses to be represented by a single node. However, I also understand it can quickly become unwieldy to place and manage individual nodes per unit for large apartment buildings, and I’m certainly not going to argue against the merged-node system. But perhaps this is a greater issue with addr:unit and addr:flats.

[Minh_Nguyen (Minh Nguyễn)]

@OptikalCrow

For the record (as I was handling the import here), 198 South Main Street in Amherst, VA (a Suite-labeled building) only shows up in that query as it shares nodes with the building next to it, which uses the Apartment label. The others in that second query appear to be office buildings with artifacts from the Virginia address dataset using inconsistent labeling and should probably be checked on the ground or with a USPS dataset. I can see genuine cases for “Apartment” and “Suite” to be used in the same building for mixed-use commercial with residential units on the higher floors.

Yes, my queries are just a rough attempt at finding cases where the designators might matter. The main limitation is that we aren’t systematically tagging them in the first place.

Aside from a few imports, most of the designators in addr:unit=* come from novice mappers who intuitively felt the need to include this information when filling out the Address field in iD. That should tell us something about the need for some sort of tagging scheme. Before we added addr:state=* to iD’s Address field, mappers would keep stuffing the state in addr:city=* to the left or addr:postcode=* to the right because they didn’t see a more obvious place for this information they had on hand.

Eventually we’d need to consider editor UI design and data consumer effects. The most convenient option for editor users is the status quo, but it means we’d need to convince data consumers (think OSM Carto) to implement U.S.-specific parsing logic to isolate the number or letter. On the other hand, a dedicated designator field beside the existing unit field could feel cluttered in mobile editors. Outside the U.S., iD has the ability to dynamically switch between addr:street=* and addr:place=* depending on what the user selects from that field, so maybe we could retain a unified unit field that sets a variety of addr:*=* subkeys under the hood.

@OptikalCrow

One of the conflicts I do see is that the addr:unit:label scheme does not play well when multiple units are represented by a single node. It is my understanding to shift to the addr:flats key to represent a range of unit numbers but I’ve never been a fan of this key as it seems to serve the exact same purpose as addr:unit but only to allow multiple addresses to be represented by a single node. However, I also understand it can quickly become unwieldy to place and manage individual nodes per unit for large apartment buildings, and I’m certainly not going to argue against the merged-node system. But perhaps this is a greater issue with addr:unit and addr:flats.

The way I think about this is that, if some or all of a building’s units are mapped individually, addr:flats=* would technically remain a valid way to indicate the full set of unit numbers within the building or beyond the entrance, implying whether the unit coverage is complete or not. Or if the units have not been mapped individually, then the building or entrance could theoretically have matching addr:unit=* and addr:flats=* (but in practice would probably just have one or the other).

Regardless, there will always be a need for multiple values in addr:unit=*. A single POI like a shop=gifts could occupy multiple units, which we don’t have enough information to map according to the simple indoor tagging scheme. Often a business owner will give their address as a pair or range of unit numbers, so a semicolon or hyphen in addr:unit=* is the most obvious response.

[Baloo_Uriza]

@OptikalCrow

For the record (as I was handling the import here), 198 South Main Street in Amherst, VA (a Suite-labeled building) only shows up in that query as it shares nodes with the building next to it, which uses the Apartment label. The others in that second query appear to be office buildings with artifacts from the Virginia address dataset using inconsistent labeling and should probably be checked on the ground or with a USPS dataset. I can see genuine cases for “Apartment” and “Suite” to be used in the same building for mixed-use commercial with residential units on the higher floors.

But do any of the suite or apartment numbers repeat, distinguished only by this difference?

[Minh_Nguyen (Minh Nguyễn)]

Again with very limited information, here are three conflicts tagged as part of addr:unit=* and four tagged as addr:unit:label=*. Some do seem trivial, like an optician in Unit B right next to an optometrist in Suite B, probably the same space. The units in this apartment building are a mix of designators, so they have fixme=* tags suspecting a simple data cleanup task. Probably one of the more common nontrivial cases would be Lower versus Upper, but these should arguably go in addr:floor=* if we don’t end up adopting something more specific.

Beyond that, it’s hard to say based on querying OSM, because we aren’t tagging the designators. The best I can do is point to this query of primary/secondary address combinations that are used the most times inside the same building. For example, Preakness Plaza in Wayne, New Jersey, contains 25 POIs all at 1211 Paterson–Hamburg Turnpike #205. But even if a unit only repeats once, that could be a case to consider. The NYS GIS SAM import also helpfully left us with over 14,000 nysgissam:review=repeat address tags indicating the same issue.

So far, all we have to go on officially is (emphasis added):

Secondary address unit designators, such as APARTMENT or SUITE, are required to be printed on the mailpiece for address locations containing secondary unit designators. The preferred location is at the end of the Delivery Address Line. The pound sign (#) should not be used as a secondary unit designator if the correct designation, such as APT or STE, is known or is shown in the ZIP+4 file.

The ZIP+4 file is authoritative as far as the postal service is concerned. Maybe your local postmaster has discretion to dispense with this formality and send you a postcard saying so? Every state, county, or town also maintains their own addressing system with their own conventions, so I hesitate to extrapolate nationally from one anecdote.

[Baloo_Uriza]

I received the postcard in Salem, Oregon and never been corrected in Portland or Tulsa subsequently, so it’s not hyper-specifically regional. It also wouldn’t surprise me if they made a big deal letting folks affected know back then that they were dropping that, and then after they did find ambiguous cases, only care if it’s a problem.

[Minh_Nguyen (Minh Nguyễn)]

@Baloo_Uriza

after they did find ambiguous cases, only care if it’s a problem.

Oh sure, they’ll only return to sender if they can’t figure out who it’s for. You can shorten “Peachtree Avenue” to just “Peachtree” if you’re mailing someone in Oklahoma City but not if you’re mailing someone in Atlanta. That doesn’t justify omitting the suffix from all the more uniquely named streets (as TIGER often does).

The designator exists in real addressing systems, if not on a handwritten envelope. It’s natural to want to tag it somehow instead of leaving it to the imagination. That leaves the question of how structured the secondary address data should be. In general OSM prefers highly structured addresses, which are helpful for labeling maps and analyzing the data but annoying for other use cases like geocoding.

[jidanni (Dan Jacobson)]

@Minh_Nguyen

Before we added addr:state=* to iD’s Address field, mappers would keep stuffing the state in addr:city=* to the left

Just like now when we stuff “Nerdsomme Street" all into the same tag because there is no better place to put “Street”. Unlike all the other systems out there.

[Tex2002ans]

This topic was perfect timing! I recently got my hands on raw data from a county’s GIS, and stumbled across these weird secondary addr:unit oddities too!

(Before this, I only ever ran across a handful of simple “Rear” or single letters like “A” / “B”.)

With some of these ambiguous ones, it’s all on a case-by-case basis on how to tag it correctly in OSM though!

---

The county has:

• ~310,000 population
• 125,929 address nodes

And here’s the breakdown of their raw secondary types:

UnitType	Count
APT	3014
UNIT	1468
TRLR	752
CONDO	556
STE	110
BLDG	51
REAR	34
OFC	3
FRNT	2
SIDE	1

(That’s the first time I ever saw a “Front” or “Side” address!)

Maybe that ratio might help roughly gauge how many are “missing” in OSM’s current data OR how big this secondary “problem” is across the US.

Apartments and Condominiums

In-person, they might look something like this:

With this county’s “APT” and “CONDO”, I haven’t taken a super close look at them on the map yet… but it seems like many of these could be condensed.

So let’s say there were 12 individual address nodes on a single building… those nodes could be condensed down to a single OSM range:

• addr:flats: 2627-2649

OR:

• addr:housenumber: 2627-2649

That info could then be added to the entire building (and/or entrance node).

---

Side Note: Or, if you wanted to go crazy… you could semicolon all those individual numbers + add levels.

---

Buildings with Letters

So, instead of 39 individual nodes, the entire building might be marked with a:

• addr:housenumber: 2216-2294
• addr:street: Milan Street
• addr:unit: F

And I tend to give the entire building a:

• name: Building F
• name: Building M

so that users can visually orient themselves on the map if needed too.

---

Apartments Note #1: That building F was just one big 4-story building with 40ish apartments inside.

That building M was a longer 3-story building, which seemed to be “cut in half” with 2 entrances, with 12 apartments each inside.

---

BLDG Note #1: In this specific county, it seemed like the “BLDG” lead to a lot of colleges/universities too.

So it might be dorms, book stores, or parts of large campus buildings.

… and then it got squished with some townhouses / industrial areas too. (So some industrial park with 6 warehouses may have had “BLDG A” → “BLDG F”.)

---

Trailer Parks (and Trailers)

With “TRLR”, at least most of the ones I’ve seen in-person, they slap a hyphen and/or letter+number on the side of the trailer.

So, you’d see a little physical rectangular plaque or sticker on the wall closest to the road:

• 123-45
• B9
• C20

which would be this in OSM:

• addr:housenumber: 123
• addr:unit: 45
• addr:street: Main Street

or:

• addr:housenumber: 123
• addr:unit: B9
• addr:street: Example Street

or:

• addr:housenumber: 456
• addr:unit: C20
• addr:street: Other Example Street

---

Trailer Note #1: In this specific county’s data though, it looks like each trailer gets their own individual housenumber… so I don’t believe TRLR is a part of that owner’s official USPS address.

So the county’s “TRLR” type was probably only there to just to help them categorize.

---

Trailer Note #2: In the case of a letter “B9” or “C20”, it probably matches the main address of the entire Trailer Park (compared to addr:street matching the nearest road).

---

Office / Business Suites

I mostly just check the business websites and see if they list “Suite” or not, then tend to go with whatever they use.

The County might list:

• STE 1 or Suite 1

but in-person, on the physical storefront, you’d potentially see:

• 100

and the business’s website might specify:

• 123 Main Street, Suite #100

or just use a simple:

• 123 Main Street

In these cases, I tend to err on the side of the business websites. They’d probably list the correct mailing address for their own business.

---

Side Note #1: In this specific county, I found a lot of stripmalls where the county may have listed: “STE 1” or “2, 3, 4, 5”, but the physical place has a “100, 200, 300, 400, 500” on the glass near the doorways.

Unsure if this is an actual error in the county data… but again, I’d lean more towards the on-the-ground physical numbers + the business’s website.

---

Side Note #2: I also tend to match whatever is on the person’s mailbox. So if their mailbox says:

• 123 Apt. 3
• 456 Rear

I’d specify it exactly that way in OSM too:

• addr:housenumber: 123
• addr:unit: Apt. 3
• addr:street: Example Street

or

• addr:housenumber: 456
• addr:unit: Rear
• addr:street: Example Street

For readability and normalization, I also remove the ALL CAPS and expand it:

• “FRNT” → addr:unit: Front
• “REAR” → addr:unit: Rear
• “STE” → addr:unit: Suite

so a human can read the label a bit easier too. Before this topic, if you handed me an “STE” and asked me what it stood for… I’d have no idea…

---

Side Note #3: In this county’s data, the “UNIT” tag was overloaded. Sometimes it mapped to the “Building Letter”, sometimes it mapped to apartments/townhouses, sometimes it duplicated “REAR”, sometimes it was just a simple “123B” street address, etc. You couldn’t really tell unless you saw the dashcam footage and took a closer look at the physical location / mailboxes to try to figure out what’s going on.

[Minh_Nguyen (Minh Nguyễn)]

Thanks for walking us through these cases. The specifics will likely differ by locality, but in general the cases you’re dealing with are probably quite common across the country.

@Tex2002ans

So, instead of 39 individual nodes, the entire building might be marked with a:

• addr:housenumber: 2216-2294
• addr:street: Milan Street
• addr:unit: F

And I tend to give the entire building a:

• name: Building F
• name: Building M

Building F is just the building’s ref=* or name=*. I’m pretty sure 2216 Milan Street doesn’t have an “F” anywhere in its full address, so “F” shouldn’t appear in any addr:*=* tag. In cases where “BLDG F” appears in the address, we clearly need to tag the “F” somewhere, but the question is whether “Building” should be indicated as well.

@Tex2002ans

The County might list:

• STE 1 or Suite 1

but in-person, on the physical storefront, you’d potentially see:

• 100

and the business’s website might specify:

• 123 Main Street, Suite #100

or just use a simple:

• 123 Main Street

The sign above the door might include or exclude “Suite”; it really depends on the building. I don’t think we should read too much into that stylistic choice. These signs usually don’t include the street name either, but we don’t omit addr:street=* on that basis.