# City 
The City API gets a city or closest city from a latitude and longitude.

It uses an algorithim that utilises spatial mapping and sophisticated data analysis to give you a blazing fast and accurate response from over 150,000 cities from every country across the globe.

This package requires an API key which can be generated [Here](https://city.rocket-solutions.co.uk/key).

<img src="https://city.rocket-solutions.co.uk/img/logo2.6271016e.png" alt="logo" width="100" height="100" />

## Installation
 
`npm i city --save`
 
## Usage

```
const city = require( 'city' )

//Using Promises
city.get( latitude, longitude, size, apiKey )
    .then( location => {
      console.log( location )
    })
    .catch( e => console.log( e ))
    
//Async await
const location = await city.get( latitude, longitude, size, apiKey )
```

## City Sizes
| Size        | Description              
| ----------- | -------------------------- |
|`NULL` | This will search through every city of every size
|`0` | Major Cities, 1m+ population
|`1` | Big Cities, 250k - 1m population
|`2` | Medium Cities, 10k - 250k population
|`3` | Small cities, under 10k population

## Demos

```
city.get( 35.4526317, 139.4546863, 0, apiKey )
//Response
{
    city: 'Yokohama'.
    country: 'JP',
    population: 3574443,
    distance: 17.823109463333083
}

city.get( 42.34133262, -83.05576000, 1, apiKey )
//Response
{
    city: 'Detroit'.
    country: 'US',
    population: 677116,
    distance: 1.3745663787473823
}
```

 ## Response
| Property      | Description
| ----------- | -------------------- |
|`city`| The city name.
|`country` | The 2 letter country code which the city is located.
|`population` | The last updated population of that city.
|`distance` | The distance between the user and city center in km.
 
 ## Errors
| Status        | Error                      | Description
| ----------- | -------------------- | ---------------------------------- |
|`422` |`API KEY NOT FOUND` | You need to pass your API key as a parameter. You can get one [Here](https://city.rocket-solutions.co.uk/key).
|`422` |`INVALID API KEY` | Your key is invalid or badly formatted.
|`422` |`INVALID SIZE` | Your size parameter is invalid.
|`402` |`NO CREDITS REMAINING` | You need to purchase more credits for your key. You can do that [Here](https://city.rocket-solutions.co.uk/key).| Icons related to the business type
|`422` |`INVALID COORDINATES` | Missing or invalid latitude/ longitude.

 ## Documentation
This is a brand new API launced in February 2021. Full Documentation will be here soon.

<s>Click [Here](https://city.rocket-solutions.co.uk/documentation) to see the full documentation</s>

## Use cases
- Location based social media
- Dating services
- Profiles
- Location based games
- Environmental evaluation
- Map and directions services