DEV Community

Investors Heaven
Investors Heaven

Posted on

I indexed 13M places to calculate real metro populations. Turns out 34.6M people live within 30 miles of Tokyo.

#api #javascript #tutorial #showdev

Here's what I mean by "real" metro population:

Tokyo's official city population: 9.7 million(city center - 23 wards)

But if you draw a 30-mile circle around Tokyo and count every city, town, and populated place inside it? 34.6 million people across 49 cities.

That's 84% of Canada's entire population, living within a 31-mile radius of one point.

The idea: Everything is a place

I kept hitting the same problem building apps with geographic data. Want to calculate the distance from New York City to Lake Tahoe? Not city to city - from a city to a lake.

Most APIs can't do this. Cities live in one database, lakes in another, mountains somewhere else. You'd need multiple services and manual coordinate math.

So I built something different. What if cities, lakes, mountains, airports, parks - all 13 million of them - lived in the same system? Same search, same filters, same calculations.

The breakthrough: feature classes.

Wait - what's a feature class?

Before I can query anything, I need to know what types of features exist. So the API has a discovery endpoint:

curl "https://cities-api10.p.rapidapi.com/feature-classes" \
  -H "x-rapidapi-key: MY_API_KEY" \
  -H "x-rapidapi-host: cities-api10.p.rapidapi.com"
Enter fullscreen mode Exit fullscreen mode

Returns:

  • P - Populated places (cities, towns)
  • T - Terrain (mountains, valleys, hills)
  • H - Hydrographic (lakes, rivers, streams)
  • S - Spots (airports, ports, stations)
  • L - Landmarks (parks, monuments, buildings)
  • A - Administrative (countries, regions)

Now I know P = cities. That's what I need for the metro calculation.

(For the rest of the examples, I'll just show the endpoint URLs - they all use the same RapidAPI headers.)

Example 1: Tokyo metro population

Step 1: Find Tokyo

/places?q=Tokyo&country=JP&class=P

Returns ID: 1850147, Population: 9,733,276

Step 2: Get metro area

/places/1850147/metro-area?radius=50

(API uses kilometers. Need miles?)

/convert/distance?value=50&from=km&to=mi

Returns: 31.07 miles

Metro area results:

  • Total population: 34,601,651
  • Cities included: 49 (Yokohama, Kawasaki, Saitama, Chiba, etc.)
  • Radius: 50km (31 miles)

The API automatically:

  1. Found all populated places within 50km
  2. Aggregated their populations
  3. Returned the breakdown

Try getting that number from Wikipedia. You'd have to manually add up dozens of cities.

Example 2: Distance from a city to a lake

Let's flip to a different feature class. I want the distance from NYC to Lake Tahoe. Remember that this is geolocation, it is straight line distance, not driving distance.

Find Lake Tahoe:
/places?q=Lake%20Tahoe&country=US&class=H → ID: 5364686

(class=H = Hydrographic features. Found it from /feature-classes)

Calculate distance:
/places/distance?from=5128581&to=5364686

Result: 3,884.8 km

Convert to miles:
/convert/distance?value=3884.8&from=km&to=mi

Result: 2,413 miles

Populated place (P) to Hydrographic feature (H). Same distance endpoint. The API doesn't care about categories - both are places with coordinates.

Example 3: Mountains near a lake

I want mountains within 20km of Lake Tahoe.

/places/5364686/nearby?class=T&featureCode=MT&radius=20

Wait - what's featureCode=MT? That's a more specific filter within the Terrain class. Check it:

/feature-codes?class=T → Shows MT (mountain), HLL (hill), VAL (valley), etc.

Results:

  • Shakespeare Point: 8.5 km
  • Eagle Rock: 11.1 km
  • South Camp Peak: 13.3 km

Convert to miles:
/convert/distance?value=8.5&from=km&to=mi → 5.28 mi
/convert/distance?value=11.1&from=km&to=mi → 6.90 mi
/convert/distance?value=13.3&from=km&to=mi → 8.26 mi

This is the same /nearby endpoint. I used it to find Terrain near Hydrographic by just changing the class filter. No special relationship needed - it just works.

Example 4: Airports near mountains

Real use case: ski trip planning. I need airports near Mount Everest.

Find Everest:
/places?q=Mount%20Everest&class=T&country=NP → ID: 1283416

Find nearby airports:
/places/1283416/nearby?class=S&featureCode=AIRP&radius=200

(class=S = Spots, which includes airports. Check /feature-codes?class=S to see all codes.)

Results (in km):

  • Tenzing-Hillary Airport: 38.6 km
  • Phaplu Airport: 62.1 km

Convert to miles:
/convert/distance?value=38.6&from=km&to=mi → 23.98 mi
/convert/distance?value=62.1&from=km&to=mi → 38.59 mi

Terrain (mountain) → Spots (airports). Different classes, same proximity search.

Example 5: Where does your city rank globally?

San Francisco's population rank:

/places?q=San%20Francisco&country=US&class=P → Get ID

/places/{id}/population-rank

Returns:

  • Global rank: #665 out of 472,412 cities
  • US rank: #21
  • Percentile: 99.86%

Try doing that with typical city APIs. You can't.

Example 6: High-altitude lakes

Say I want lakes in Switzerland above 1,500m elevation:

/places?country=CH&class=H&featureCode=LK&minElevation=1500

I'm combining:

  • Geographic filter (country)
  • Feature class (Hydrographic)
  • Specific type (lake)
  • Elevation filter

Found: Spilauer See at 1,837m

Convert elevation to feet:
/convert/elevation?value=1837&from=m&to=ft → 6,027 ft

The agnostic model means you can combine filters however you want - the API doesn't have predefined "use cases." You compose your own.

The pattern

Here's how you discover and query anything:

  1. Check available classes: /feature-classes
  2. Pick your class: P, T, H, S, L, or A
  3. Optionally get specific: /feature-codes?class=X for detailed types
  4. Query with class: /places?class=X&featureCode=Y
  5. Use any endpoint: distance, nearby, metro-area, population-rank - all accept any class
  6. Convert units as needed: /convert/distance, /convert/elevation

Same endpoints, same filters, same logic. Just change the class parameter.

This unlocks combinations that weren't possible:

  • Metro population for any city: /places/{id}/metro-area?radius=50
  • Distance from city to lake: /places/distance?from={city}&to={lake}
  • Mountains near lakes: /places/{lake_id}/nearby?class=T&featureCode=MT
  • Airports near mountains: /places/{mountain_id}/nearby?class=S&featureCode=AIRP
  • High-elevation lakes: /places?class=H&featureCode=LK&minElevation=1500
  • Convert any distance or elevation: /convert/distance, /convert/elevation

What you could build with the API (among many things)

  • Demographic tools - Calculate real market sizes using metro area aggregation
  • Travel planners - Find airports near mountains, cities near lakes
  • Real estate apps - Population ranks, metro area growth analysis
  • Logistics tools - Find ports, airports, cities along routes

The pattern is the same: check /feature-classes, pick what you need, compose your query.

It's on RapidAPI now with 84 endpoints covering places, countries, timezones, postal codes, and unit conversions. Free tier available.

Docs: https://hthought.github.io/cities-api-docs

What would you calculate with this? What metro areas would you compare? Drop a comment.

Top comments (0)