CitiesBrazil API

A Rest API that helps you to get all the cities in Brazil 🚀

📌 Table of Contents

• Features
• Requirements
• Installation
• Getting Started
• FAQ
• Found a bug? Missing a specific feature?
• Contributing
• License

🚀 Features

• GET List of Brazilian Cities and States, and Countries.
• GET each Brazilian City and State, and Country by Id.
• GET a straight line distance between two Brazilian Cities.

Nearby cities query will be added soon.

Requirements

For building and running the application you need:

• JDK 8
• Gradle
• Docker to run PostgreSQL image or PostgreSQL installed locally

👷 Installation

To install this application, run the following commands:

git clone https://github.com/iamgrodrigues/citiesbrazil-api.git

If you have a SSH key registered in your Github account, clone the project using this command:

git clone [email protected]:iamgrodrigues/citiesbrazil-api.git

🏃 Getting Started

Running the application locally

There are several ways to run a Spring Boot application on your local machine. One way is to execute the main method in the com.iamgrodrigues.citiesbrazilapi.CitiesBrazilApiApplication class from your IDE.

Alternatively you can use the Spring Boot Gradle plugin like so:

gradle bootRun

After the above command, you can navigate to the following address to see the project up and runnig:

http://localhost:8080/cities

Running docker container

Note: Skip this part if you have PostgreSQL installed

Once you've installed Docker run the following command: that will start up the PostgreSQL container on 5432:5432 port, set up enviroment variables for user and password, and create a database called cities.

docker run --name cities-db -d -p 5432:5432 -e POSTGRES_USER=postgres_user_city -e POSTGRES_PASSWORD=super_password -e POSTGRES_DB=cities postgres

Populate the database

Note: If you already have PostgreSQL installed on your machine, skip the docker related commands.

Gitclone the following repository, please show the man some love by starring his repository, he has done an amazing work populating all of those datas into this database.

https://github.com/chinnonsantos/sql-paises-estados-cidades.git

Once you done clonning it, navigate to the /PostgreSQL folder and run these commands:

docker run -it --rm --net=host -v $PWD:/tmp postgres /bin/bash

psql -h localhost -U postgres_user_city cities -f /tmp/pais.sql
psql -h localhost -U postgres_user_city cities -f /tmp/estado.sql
psql -h localhost -U postgres_user_city cities -f /tmp/cidade.sql

In order to do the distance calculation you will need to create the Earthdistance extension in the database, you can achieve that by running these commands:

psql -h localhost -U postgres_user_city cities

CREATE EXTENSION cube; 
CREATE EXTENSION earthdistance;

Status Codes

CitiesBrazil returns the following status codes in its API:

Status Code	Description
200	OK
400	BAD REQUEST
500	INTERNAL SERVER ERROR

Error handling will be added soon.

📮 Faq

Question: What are the tecnologies used in this project?

Answer: The tecnologies used in this project are Java + Spring Boot and PostgreSQL.

🐛 Issues

Feel free to file a new issue with a respective title and description on the the CitiesBrazil API repository. If you already found a solution to your problem, I would love to review your pull request! Have a look at our contribution guidelines to find out about the coding standards.

🎉 Contributing

Check out the contributing page to see the best places to file issues, start discussions and begin contributing.

📕 License

Released in 2021. This project is under the MIT license.

Made with love by Guilherme Rodrigues 💚🚀