DEV Community

Rafael Magalhaes
Rafael Magalhaes

Posted on

My first npm package

Recently, I was looking for an API that provided country and city data, but I couldn't find anything that fit the bill. Some APIs had country info but left out the cities, while others were just way too expensive, like Google Places.

The requirements for the country were the name, flag, and country code, and for the city, it was just the name and country.

Then, I found two projects that had exactly what I was looking for:

  • Cities.json: A super cool GitHub repo with a massive list of cities in a handy JSON format.
  • Restcountries API: A detailed country data.

Merging Data: The Birth of [@rrrm/countries](

To create a unified solution, I merged data from Cities.json and the Restcountries API. The result is the @rrrm/countries NPM package, named after my initials and the focus of the package.

Key Features of @rrrm/countries

  • Country and City Information: Access to a wealth of data on countries and cities worldwide.
  • User-Friendly Integration: An NPM package that simplifies integration into your projects.


import { findCities, findCountry, getAllCitiesByCountry } from "@rrrm/countries"

// find cities with country information
const lisbon = findCities("lisbon", { withCountry: true })
console.log("findCities-> ", lisbon)

// find a country with all cities
const pt = findCountry("PT", { withCity: true })
console.log("findCountry-> ", pt)

// get all cities for  a country
const citiesBycountry = getAllCitiesByCountry("PT")
console.log("getAllCitiesByCountry-> ", citiesBycountry)

Enter fullscreen mode Exit fullscreen mode

Check out the repository here

Data Files

I have also created two helper functions to convert the results to JSON or CSV:

  • convertJson(fileName: string, data: any | Country[] | City[]): Convert data to JSON format and save it to a file.
  • convertCSV(fileName: string, data: any | Country[] | City[]): Convert data to CSV format and save it to a file.
import { convertJson, convertCSV } from './convert.ts';

const data = [{ /* Your data here */ }];
convertJson('data.json', data);
convertCSV('data.csv', data);
Enter fullscreen mode Exit fullscreen mode

I ended up using this to create a CSV to import the data into my Supabase project.

I have added a folder schema with some SQL migrations to create the tables for the city and country.

This has been a really fun project, and I hope it's useful to any of you.

Top comments (2)

christianpaez profile image
Christian Paez

Good job, keep it up!

pxlmastrxd profile image

Great job on your first NPM package!