Places API

A RESTful places API built using Laravel framework.
API »

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Running the Application
3. Documentation
4. Like My Work?
5. License
6. Contact
7. Acknowledgements

About The Project

Places API is a RESTful api based on the Geonames database. You can use this API to explore the world!

Built With

• Laravel framework
• Bulma
• Swagger UI

Getting Started

To get a local copy up and running follow these simple example steps.

Prerequisites

We recommend settings up and running the project using Docker and Docker Compose.

You will need:

1. PHP 8.2
2. Composer
3. Node Package Manager (NPM)
4. Docker
5. Docker Compose

Running the Application

1. Clone the repository

   git clone https://github.com/NizarBerjawi/places-api.git

2. Create an .env file

   cp .env.example .env

3. Install composer packages

   docker compose run --rm composer install

4. Install npm packages

   docker compose run --rm npm install

5. Generate Open API spec

   docker compose run --rm artisan docs:generate

6. Build assets

   docker compose run --rm npm run build

7. Migrate the database

   docker compose run --rm artisan migrate:fresh

8. Generate an application key

   docker compose run --rm artisan key:generate

At this point you can already start up the application, however there won't be any data in the database. To start the application without data, exit the interactive shell and jump to step 11 below, otherwise just keep on going through the steps below.

Please note that downloading and importing the data will download ALL the Geonames dump export files and then imports them into the database. Depending on your CPU power, This process could take up to several hours to complete.

9. Push the file download jobs to the queue

   docker compose run --rm artisan geonames:download

   Then process the queue:

   docker compose run --rm artisan queue:work --stop-when-empty --queue=download-data,download-places,download-flags,download-names

10. When all the files have been downloaded, push the file import jobs to the queue

docker compose run --rm artisan geonames:import

Then process the queue:

docker compose run --rm artisan queue:work --stop-when-empty --queue=import-data,import-places,import-names

11. Start the application server

    docker compose up --build nginx

12. Open the application in a browser

    http://localhost:8080

Documentation

For a full details, please refer to the Documentation.

Like My Work?

If you like my work and find that this project helps, please support!

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

If you find any issues, please contact the developer:

Nizar El Berjawi - [email protected]

Acknowledgements

• GeoNames
• Laravel framework