Skip to content

shivammathur/countrycity

Repository files navigation

Country City API

Build Status Code Climate codecov License

Geodata API to get the list of countries and cities in the world. This can be plugged in country and city picker drop-downs in forms. You can find a select2 implementation here. Code for this implementation is in example directory.

⚡ Installing the CountryCity API

  • Make sure you have PHP 7.4 or newer.
$ php -v
  • Download this API using composer using the command below.
composer global require shivammathur/countrycity "dev-main"
  • Then install the API by executing the command below.
composer create-project shivammathur/countrycity countrycity "dev-main" --prefer-dist
  • You are all set, you can use this API.

#️⃣ API Endpoints

All API responses are in json format.

  • Get all countries
/countries

# Without URL Rewriting
/index.php/countries
  • Get all countries containing a search keyword
/countries/{search_keyword}

# Without URL Rewriting
/index.php/countries/{search_keyword}
  • Get all cities in a country
/cities/{country}

# Without URL Rewriting
/index.php/cities/{country}
  • Get all cities in a country containing a search keyword
/cities/{country}/{search_keyword}

# Without URL Rewriting
/index.php/cities/{country}/{search_keyword}

✨ Rest API Features

  • Built using Slim micro framework.
  • Caching enabled with following headers
    • ETag
    • Expires
    • Last-Modified
  • Fast and lightweight API
  • PSR 7 Complaint
  • CORS Middleware

☁️ Hosting configuration

Here are the Configuration Instructions if you want to host this on your server.

🔧 Error Format

If there is an error in the API, you will get an error in json format as response

{"error":"true", "message": "error message here"}

🚨 Testing

$ vendor/bin/phpunit --configuration phpunit.xml.dist

📜 License

The scripts and documentation in this project are released under the MIT License. This project has multiple dependencies and their licenses can be found in their respective repositories.

👍 Contributions

Contributions are welcome! See Contributor's Guide.

💖 Support this project

  • Please star the project and share it with the community.
  • Support the project by sponsoring my work on GitHub sponsors.