The city on an address is a mailing convention. In the US it is the USPS city for the ZIP code. In the UK it is the Royal Mail post town, named for the delivery office that serves the address. Neither has to be the town the address is in, which is why support tickets that start with "the API says Arlington but I live in Clarendon" are so common.

Geocodio's gazetteer append answers a different question: what is this place called, and what is it part of? For each address or coordinate pair it returns the town or community the point is in or nearest to, its county, the local authority that serves it, and the official code for each, from the agency that publishes it. For Great Britain it also returns the UPRN and USRN. It works with forward and reverse geocoding in the US, UK, Canada, Mexico, Australia, and New Zealand, and it counts as one field append per address, charged only when something comes back.

Why doesn't the city on an address match the town?

Because the city on an address was never meant to say where the address is. It was meant to get a letter delivered. Every country has the same gap, each with its own vocabulary.

• United States. address_components.city is the USPS city for the ZIP code. The census append's place is a statistical boundary: an incorporated city or a Census Designated Place (CDP). Take 1109 N Highland St, Arlington, VA 22201. The USPS city is Arlington. Arlington County has no incorporated towns, so the Census Bureau draws one CDP over the whole county, and census.place says Arlington too. The neighborhood anyone there would name is Clarendon, and that is what gazetteer returns.

• United Kingdom. The post town is a delivery convention and often names a different town from the one the address is in. The village of Chapel Stile in the Lake District has Ambleside as its post town. On top of that, "county" means three different things in the UK (the ceremonial county, the historic county, and the council that serves you), and anyone joining UK property data wants the UPRN in the same lookup.

• Canada. Tens of thousands of named communities have no Statistics Canada geography of their own. Portuguese Cove, Nova Scotia is a real place with a name in the national gazetteer, but the smallest municipality StatCan knows is the Halifax Regional Municipality, which runs for 5,500 square kilometres. In a big city the opposite is true: the municipality is the answer, and Toronto comes back as Toronto with its Statistics Canada code.

• Mexico. Addresses are organized by municipio, but people live in a localidad. Cancún is a localidad inside the municipio of Benito Juárez, and both have an official INEGI clave that nothing on the address carries.

• Australia and New Zealand. The address already names the suburb, which is the right level for mail. What is missing is the council. Australia returns the Local Government Area. New Zealand returns the town people say they live in (Rotorua, when the suburb is Koutu) and the territorial authority.

Here is the same gap on real lookups. Every value in the table is a live response from the Geocodio API.

What does the gazetteer append return?

fields.gazetteer always has the same four slots, whichever country the address is in, so you can read the response without a country switch.

• geographic_town: the town, city, village, or settlement the point is in or nearest to.

• county: ceremonial and historic. Filled in the UK, plus historic for Connecticut.

• authority: local and regional. The council or municipality that serves the address, and the county council above it in two-tier England.

• identifiers: uprn and usrn for Great Britain. null everywhere else.

Every place (geographic_town, each county, each authority) is an object with a name, a names map with the name in each language the publisher records (see "What language are place names in?" below), a type (what kind of place this is, such as built_up_area or municipio), a code keyed by the code system ({ "gss_code": "E07000094" }), and a source naming the publisher. Counties have no type, and a place with no official code has no code key.

A slot that is null means Geocodio checked and there is nothing there. It does not mean the lookup failed. When the whole gazetteer key is missing from a result, the append did not apply (an unsupported country, a match at state or county level, or every slot empty) and you were not charged for it.

{
  "gazetteer": {
    "geographic_town": {
      "name": "Winchester",
      "names": { "en": "Winchester" },
      "type": "built_up_area",
      "code": { "gss_code": "E63020415" },
      "source": "Ordnance Survey"
    },
    "county": {
      "ceremonial": { "name": "Hampshire", "names": { "en": "Hampshire" }, "source": "Ordnance Survey" },
      "historic": { "name": "Hampshire", "names": { "en": "Hampshire" }, "source": "Historic Counties Trust" }
    },
    "authority": {
      "local": {
        "name": "Winchester",
        "names": { "en": "Winchester" },
        "type": "non_metropolitan_district",
        "code": { "gss_code": "E07000094" },
        "source": "Office for National Statistics"
      },
      "regional": {
        "name": "Hampshire",
        "names": { "en": "Hampshire" },
        "type": "county",
        "code": { "gss_code": "E10000014" },
        "source": "Office for National Statistics"
      }
    },
    "identifiers": {
      "uprn": { "value": "200000189250", "source": "Ordnance Survey" },
      "usrn": { "value": "44304622", "source": "Ordnance Survey" }
    }
  }
}

That is the response for Winchester Cathedral, The Close, Winchester SO23 9LS. Hampshire appears three times because it is a two-tier county: Hampshire County Council is the regional authority, and Hampshire is also both the ceremonial and the historic county. In Edinburgh the three disagree, which is covered in which county is a UK address in?.

Which slots are filled in each country?

The null slots for the US and Canada are deliberate. Counties, county subdivisions, census divisions, and the rest already live in the census and statcan appends, and every US result carries address_components.county for free, so the gazetteer does not repeat them.

What do the codes mean?

Each code object has one key, named for the system that issued it, so you always know what you are joining on.

US incorporated places, UK nearest-settlement fallbacks, and New Zealand towns carry no code. The Census Bureau's place FIPS code is in the census append if you need it.

What language are place names in?

Every named place carries a names map next to name, keyed by BCP 47 language tag, such as { "en": "Cardiff", "cy": "Caerdydd" }. The value in name is always one of the entries in names, so use name when you need a single string and names when you want a particular language.

In Wales and Scotland, Welsh and Scottish Gaelic have equal status with English. Ordnance Survey publishes Welsh and Scottish Gaelic town names and the Office for National Statistics publishes Welsh council names, so a Cardiff address returns Caerdydd under cy for both the town and the council, and Corpach, outside Fort William, returns A'Chorpaich under gd. Counties and Scottish councils have no Welsh or Scottish Gaelic names in the published data, and Northern Ireland names are English only.

To show the Welsh name wherever one exists, read names.cy and fall back to name: names.cy ?? name. The same pattern works for names.gd.

{
  "gazetteer": {
    "geographic_town": {
      "name": "Cardiff",
      "names": { "en": "Cardiff", "cy": "Caerdydd" },
      "type": "built_up_area",
      "code": { "gss_code": "W45001843" },
      "source": "Ordnance Survey"
    },
    "county": {
      "ceremonial": {
        "name": "South Glamorgan",
        "names": { "en": "South Glamorgan" },
        "source": "Ordnance Survey"
      },
      "historic": {
        "name": "Glamorgan",
        "names": { "en": "Glamorgan" },
        "source": "Historic Counties Trust"
      }
    },
    "authority": {
      "local": {
        "name": "Cardiff",
        "names": { "en": "Cardiff", "cy": "Caerdydd" },
        "type": "unitary_authority",
        "code": { "gss_code": "W06000015" },
        "source": "Office for National Statistics"
      },
      "regional": null
    },
    "identifiers": { "uprn": null, "usrn": null }
  }
}

That is Cardiff Castle, Castle Street, Cardiff CF10 3RB. The identifiers are null because the castle matched as a nearest_rooftop_match rather than a rooftop.

Spreadsheet uploads, once the gazetteer append is available there, add Geographic Town (Welsh), Geographic Town (Scottish Gaelic), and Local Authority Name (Welsh) columns for the same values.

What you get in each country

United Kingdom

The UK is where the gazetteer does the most work, because the UK has the most names for one place.

• Town. The Ordnance Survey built-up area the point falls in, with its GSS code. Outside any built-up area (a rural address, say) it is the nearest Ordnance Survey settlement, typed as city, town, village, hamlet, suburban_area, or other_settlement, with no code. Northern Ireland uses NISRA settlements, which do have GSS codes.

• Ceremonial county. From Ordnance Survey Boundary-Line. Scotland uses lieutenancy areas, Wales uses preserved counties, and Northern Ireland uses the six counties from Land and Property Services (OSNI).

• Historic county. From the Historic Counties Trust, using its Definition A boundaries. This is why Edinburgh returns Midlothian and 10 Downing Street returns Middlesex.

• Local authority. The council that serves the address, from the Office for National Statistics: a unitary authority, non-metropolitan district, metropolitan district, London borough, Scottish council area, or Northern Ireland local government district.

• Regional authority. The county council, which only exists in two-tier England. It is null for London, unitary authorities, Scotland, Wales, and Northern Ireland.

• Identifiers. The UPRN and USRN from Ordnance Survey, for rooftop and point matches in Great Britain. See how to get a UPRN for an address.

The name is the English name, so Cardiff. Welsh and Scottish Gaelic names sit beside it in names wherever Ordnance Survey or the ONS publishes one, so Caerdydd is there under cy. See "What language are place names in?" above.

{
  "gazetteer": {
    "geographic_town": {
      "name": "City of Westminster",
      "names": { "en": "City of Westminster" },
      "type": "built_up_area",
      "code": { "gss_code": "E63019250" },
      "source": "Ordnance Survey"
    },
    "county": {
      "ceremonial": { "name": "Greater London", "names": { "en": "Greater London" }, "source": "Ordnance Survey" },
      "historic": { "name": "Middlesex", "names": { "en": "Middlesex" }, "source": "Historic Counties Trust" }
    },
    "authority": {
      "local": {
        "name": "Westminster",
        "names": { "en": "Westminster" },
        "type": "london_borough",
        "code": { "gss_code": "E09000033" },
        "source": "Office for National Statistics"
      },
      "regional": null
    },
    "identifiers": {
      "uprn": { "value": "100023336956", "source": "Ordnance Survey" },
      "usrn": { "value": "8400071", "source": "Ordnance Survey" }
    }
  }
}

That is 10 Downing Street. authority.regional is null because London has no county council.

United States

geographic_town is the incorporated place that contains the point, from the U.S. Census Bureau. If the point is not inside one, it is the nearest populated place from the USGS Geographic Names Information System, with its gnis_feature_id. Seattle addresses return Seattle. The Arlington address above returns Clarendon.

county.historic is filled for Connecticut only. The Census Bureau replaced Connecticut's eight counties with nine planning regions in 2022, and Geocodio's standard county field followed, but courts, local media, and most residents still use the old counties. The gazetteer returns the pre-2022 county, such as Hartford County, so you can keep both. The background is in what happened to counties in Connecticut?

Everything else is null for US addresses. Your county is already in address_components.county on every result, and county subdivisions, tracts, and places with FIPS codes are in the census append.

{
  "gazetteer": {
    "geographic_town": {
      "name": "Clarendon",
      "names": { "en": "Clarendon" },
      "type": "populated_place",
      "code": { "gnis_feature_id": "1499266" },
      "source": "U.S. Geological Survey"
    },
    "county": { "ceremonial": null, "historic": null },
    "authority": { "local": null, "regional": null },
    "identifiers": null
  }
}

Canada

geographic_town is the census subdivision that contains the point when that subdivision is a city, town, or village, with its Statistics Canada sgc_code. When the point is not inside one of those (a regional municipality or a rural district, for example), it is the nearest named place from the Canadian Geographical Names Database, with its cgndb_id and Natural Resources Canada as the source.

Everything else is null. Census divisions, consolidated subdivisions, economic regions, and the full subdivision record are in the statcan append.

{
  "gazetteer": {
    "geographic_town": {
      "name": "Portuguese Cove",
      "names": { "en": "Portuguese Cove" },
      "type": "unincorporated_place",
      "code": { "cgndb_id": "CBENO" },
      "source": "Natural Resources Canada"
    },
    "county": { "ceremonial": null, "historic": null },
    "authority": { "local": null, "regional": null },
    "identifiers": null
  }
}

Mexico

geographic_town is the urban localidad from INEGI that contains the point, with its nine-digit inegi_clave. Outside any urban localidad it is the nearest rural localidad. When the localidad has the same name as the municipio, as in Guadalajara, geographic_town is null so the same name does not appear twice.

authority.local is the municipio, or the alcaldía in Mexico City, with its five-digit inegi_clave.

{
  "gazetteer": {
    "geographic_town": {
      "name": "Cancún",
      "names": { "es": "Cancún" },
      "type": "urban_locality",
      "code": { "inegi_clave": "230050001" },
      "source": "Instituto Nacional de Estadística y Geografía (INEGI)"
    },
    "county": { "ceremonial": null, "historic": null },
    "authority": {
      "local": {
        "name": "Benito Juárez",
        "names": { "es": "Benito Juárez" },
        "type": "municipio",
        "code": { "inegi_clave": "23005" },
        "source": "Instituto Nacional de Estadística y Geografía (INEGI)"
      },
      "regional": null
    },
    "identifiers": null
  }
}

Australia

Australian addresses already carry the suburb in address_components.city and the state in address_components.state, so geographic_town is null. What the gazetteer adds is authority.local: the Local Government Area, the council that sets rates and collects the bins. The name is the common one (Sydney, Toowoomba, Coober Pedy), the type is local_government_area, and the code is the Australian Bureau of Statistics LGA code in abs_lga_code. Boundaries come from Geoscape Australia and names and codes from the ABS. The county slots, authority.regional, and identifiers are null.

Not every Australian address has a council. The Australian Capital Territory has no local government, and parts of the Northern Territory and South Australia are unincorporated, so an address in Canberra or Yulara returns no gazetteer key at all and is not billed for the append.

{
  "gazetteer": {
    "geographic_town": null,
    "county": { "ceremonial": null, "historic": null },
    "authority": {
      "local": {
        "name": "Sydney",
        "names": { "en": "Sydney" },
        "type": "local_government_area",
        "code": { "abs_lga_code": "17200" },
        "source": "Geoscape Australia"
      },
      "regional": null
    },
    "identifiers": null
  }
}

That is 1/199 George St, The Rocks NSW 2000. The suburb, The Rocks, is in address_components.city, and the council is the City of Sydney.

New Zealand

In New Zealand, address_components.city is the LINZ suburb or locality, which can be a name nobody outside the district knows. geographic_town is the LINZ town or city, typed city, town, or major_locality, with no code. An address in the suburb of Koutu returns Rotorua. authority.local is the territorial authority from Stats NZ under its official name, so the council for that same address is Rotorua District, with its territorial_authority_code. The type is city, district, unitary_authority for Auckland and the other unitary councils, or territory for the Chatham Islands. The county slots, authority.regional, and identifiers are null.

{
  "gazetteer": {
    "geographic_town": {
      "name": "Rotorua",
      "names": { "en": "Rotorua" },
      "type": "city",
      "source": "Toitū Te Whenua Land Information New Zealand (LINZ)"
    },
    "county": { "ceremonial": null, "historic": null },
    "authority": {
      "local": {
        "name": "Rotorua District",
        "names": { "en": "Rotorua District" },
        "type": "district",
        "code": { "territorial_authority_code": "024" },
        "source": "Stats NZ"
      },
      "regional": null
    },
    "identifiers": null
  }
}

That is 117 Fairy Springs Rd, Koutu. Auckland addresses return Auckland as both the town and the unitary authority, code 076.

What does "in or nearest to" mean?

Some towns come from a boundary polygon the point falls inside: Ordnance Survey built-up areas, Census incorporated places, Statistics Canada census subdivisions, INEGI urban localidades. Others come from the nearest point in a gazetteer of named places: Ordnance Survey settlements, USGS populated places, Canadian Geographical Names Database places, rural localidades. The point-based lookups have no distance cutoff. A remote address is named after the nearest community even when that community is a long way off, so read geographic_town as "the community this address is in or nearest to", never as "inside the boundary of".

To keep that from becoming a guess, nearest-point towns are only returned for street-level or better matches, which includes intersections. For a place or nearest_place result, a town that would have come from the nearest point is null. Towns that come from a polygon are still returned, which is why the postcode SO23 8UJ on its own still returns Winchester: the postcode centroid sits inside the Winchester built-up area.

The same gate applies to identifiers. The UPRN and USRN are returned for rooftop and point matches in Great Britain and are null for everything else, including nearest_rooftop_match.

How is this different from address_components.city, census.place, and statcan?

They answer different questions, and the right one depends on what you are doing.

If you need one rule: use address_components.city for mail, and gazetteer.geographic_town for "what is this place called".

How much does the gazetteer append cost?

Geocoding and reverse geocoding lookups cost 1 credit each. The gazetteer append adds 1 credit per address, however many of the slots it fills. So an address with fields=gazetteer costs 2 credits.

You are not charged for the append when the gazetteer key is missing from a result: unsupported countries, matches at state or county level, and lookups where every slot would have been empty. A reverse geocode of 44.5200, -63.5100 off the Nova Scotia coast, for example, matches at nearest_place accuracy, returns no gazetteer, and bills only the lookup.

UK addresses need a Flex plan or a UK-enabled Unlimited subscription, as with every UK lookup.

How do I request it?

Add gazetteer to the fields parameter on any geocode or reverse geocode request in API v2. It can be combined with other appends, comma-separated, and works in batch requests.

curl "https://api.geocod.io/v2/geocode?q=Winchester+Cathedral,+The+Close,+Winchester+SO23+9LS&country=GB&fields=gazetteer&api_key=YOUR_API_KEY"

curl "https://api.geocod.io/v2/reverse?q=54.4560,-3.0880&fields=gazetteer&api_key=YOUR_API_KEY"

The full response schema, with the type values for every country, is in the API documentation.

Spreadsheet uploads. The gazetteer append is available through the API today. Support in the spreadsheet upload tool is being released separately. Once it is there you will find it in Step 3 (Data Appends) with the other appends, flattened into one column per slot so a mixed-country spreadsheet keeps a single set of headers.

Attribution and licences

Every place and identifier carries a source. If you display or redistribute the values, show the publisher named there. Two publishers ask for specific wording:

• Historic Counties Trust (county.historic in the UK) asks to be credited when its county data is used.

• INEGI (every Mexican value) asks for: "Fuente: INEGI, Marco Geoestadístico Integrado, Encuesta Intercensal 2025".

Ordnance Survey, Office for National Statistics, and NISRA data is published under the Open Government Licence v3.0. Geoscape Australia and the Australian Bureau of Statistics (Australia), and Toitū Te Whenua Land Information New Zealand and Stats NZ (New Zealand), publish under CC BY 4.0. The attribution lines for the UK publishers are listed in the UK census geographies guide.