OpenStreetMap Nominatim schema inconsistencies

I am trying out the OpenStreetMap Nominatim reverse-geocoder RESTFul API.

Is there a definitive explanation of the address schema returned from the API? Some locations have different attributes in the ‘addressparts’ block.

For example, for Seattle, Nominatim includes “suburb” and “city” attributes.

    <road>9th Avenue</road>
    <suburb>First Hill</suburb>
    <country>United States of America</country>

However, for New York City, it returns “neighborhood” and “state_district” attributes.

    <address29>N.Y. Grill & Deli</address29>
    <road>Rivington Street</road>
    <neighbourhood>Lower East Side</neighbourhood>
    <state_district>New York City</state_district>
    <county>New York</county>
    <state>New York</state>
    <country>United States of America</country>

About this special topic you can try to ask OSM user lonvia … she is quite active at, see

or at the OSM wiki:

Thank you for the pointer; I’ll contact her. However, I don’t understand why this is a special topic. Surely the address schema inconsistency must be a very general problem, no?

OSM doesn’t really do consistency.

Looks like it depends on how the object is tagged in OSM.