[Bug]: Counties should not be returned separately with cities

[NDCallahan]

Issue Type

Other

Location (if applicable)

City

What's wrong?

When retrieving the city information from the states, it appears the data also includes every county that the city is in as well. Instead of providing a clean list of cities, the data mixes in the county for the cities as well.

A county is to a state like a state is to the nation. They are just sub-divisions of the state with their own level of government that creates legislation and what not for a smaller area. They were created so that all state land is in a county.

What should it be?

If I am pulling back cities from states, I should not be also getting counties. That should be a separate endpoint in my honest opinion. This makes the data a bit messy when you are just looking for the cities that are in a state while not wanting to know which county that city sits in.

Hierarchy is Country --> State --> County --> City ( at least for the United States of America)

Source (optional)

https://learningenglish.voanews.com/a/city-district-county-town-what-are-the-differences-/5893801.html

[dosubot]

Hi @NDCallahan! I'm Dosu and I’m helping the countries-states-cities-database team.

For the United States, the data model links cities directly to states and does not explicitly include counties in city lists—cities are associated only with states in the JSON files and documentation. There is no field for counties in the city data, so you should only get cities when querying by state, not counties mixed in.

Mixing of administrative levels (like counties and cities) has been a known issue in other countries, and the repository has addressed this by introducing hierarchical fixes and using fields like type and parent_id to separate them. If you see counties appearing with cities in your results, it may be due to legacy data or incomplete separation, which has been recognized as a broader problem in the past and addressed for other regions (see issue #1019, Bangladesh fix, Taiwan fix, Estonia fix).

To ensure you only get cities, filter your results by state_id/state_code and, if present, ignore any entries with a type of "county" or similar. If you continue to see counties mixed in, it may be worth reviewing the data export or API response for unexpected types or legacy records. The repository has a track record of improving hierarchical accuracy, so future updates may further clarify these boundaries.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[NDCallahan]

@dosu You can see in this single API call that the returned data is including both the city and the county.

[dosubot]

You're right—counties are being returned alongside cities in the API response, which is a known data quality issue in this project and has affected other countries as well. The repository has addressed similar problems elsewhere by introducing hierarchical fields like type and parent_id to separate administrative levels, but for the US, the City model doesn't have a type field, so it's hard to filter out counties from cities directly in the response. The State model does have a type field, which can sometimes help with filtering if you cross-reference city state_id with state type, but this isn't always straightforward for API consumers [schema reference].

For now, you may need to filter out entries with known county names or use the state type field if available. The invalid longitude value you spotted (e.g., 191.30396000) is also a data issue—recent validation checks were supposed to ensure all coordinates are within valid ranges, so this may be a legacy or missed record [coordinate validation PR].

Recent pull requests have focused on fixing state and city naming/classification, which may help, but a full hierarchical fix for the US (like those done for Taiwan and Bangladesh) would be the best long-term solution [hierarchical fix example]. If you need clean city data now, client-side filtering and coordinate validation are your best options.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[dr5hn]

Thanks for raising this — you're right, and the data confirms it.

What's actually in US.json

I just checked the current US cities dataset (19,788 records):

type	Count	Notes
city	13,318	✅ legitimate cities
adm2	2,995	❌ admin level 2 (counties under another name)
county	2,993	❌ counties
section	338	⚠️ usually subdivisions of cities
parish	64	❌ Louisiana parishes (= counties)
municipality	3	✅ valid
other	~80	adm1/adm3/capital/etc.

So roughly 30% of US "city" records are actually county-level administrative units, not cities. You're seeing exactly what the dataset contains.

Workaround you can use today

Every record has a type field. Filter by it:

cities.filter(c => c.type === 'city' || c.type === 'municipality' || c.type === 'capital')

Or, for SQL consumers:

SELECT * FROM cities WHERE type IN ('city', 'municipality', 'capital');

This gives you a clean ~13,300 US cities without the county/adm2/parish entries.

Path to a proper fix

You're right that ideally counties shouldn't share a table with cities. The repo has done country-by-country reclassifications before — see #1216 (Bangladesh), #1267 (Taiwan), #1286 (Estonia). A US cleanup would mean:

1. Move all type IN ('county', 'parish', 'adm2', 'adm3') records out of contributions/cities/US.json
2. Decide where they go — either drop entirely (if not useful), or move to a new contributions/counties/US.json file (if downstream consumers want them as a separate dataset)
3. Update the schema docs to clarify what cities/ contains

This is a meaningful structural change (~6,000 records affected) and benefits from broader community input on point 2. I'll keep this issue open as a tracking issue for that work.

In the meantime, the type filter above should unblock your use case. Let me know if you'd like to contribute the cleanup PR — happy to coordinate.

---

(Note: the longitude 191.30396000 you spotted in the screenshot looks like it's been fixed in a more recent export — current US.json has 0 longitudes outside the valid −180..180 range. If you're still seeing it on a downstream package, you may be on a stale version.)

[NDCallahan]

Thanks! I can definitely use the type filter for now to have the dataset be more clean. I would think we would want counties to be separate. Hopefully more folks will agree! :)