## Cities related end points

Pagination:
see [PagingAndSorting.md](../PagingAndSorting.md) 

## List Cities ##

### GET - api/v1/cities

Path parameters:
* order[by] - possible values are: name, id
* filter[name] - used for autocomplete functions; search by city name
* filter[ids] - Accepts a set of ids

#### Example request:
/api/v1/cities?paging[page]=1&paging[items_per_page]=2&order[by]=name&order[direction]=desc


##### Response:
```json
{
    "data": [
        {
            "id": 7,
            "name": "Setubal",
            "mapPositionLat": 39.147102707701,
            "mapPositionLng": -0.3515625,
            "mapPositionZoom": 1,
            "description": ""
        },
        {
            "id": 2,
            "name": "Oporto",
            "mapPositionLat": 24.906367237908,
            "mapPositionLng": 5.9765625,
            "mapPositionZoom": 1,
            "description": ""
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_items": 8,
        "per_page": 2,
        "total_pages": 4
    }
}

```


#### Example request: 
api/v1/cities?filter[name]=oei&paging[page]=1&paging[items_per_page]=2&order[by]=name&order[direction]=desc


##### Response:

```json
{
    "data": [
        {
            "id": 8,
            "name": "Oeiras",
            "mapPositionLat": 17.035777250427,
            "mapPositionLng": -1.0546875,
            "mapPositionZoom": 1,
            "description": ""
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_items": 1,
        "per_page": 2,
        "total_pages": 1
    }
}
```

#### Example request with ids: 
/api/v1/cities?filter[ids]=1,2,3

##### Response:

```json
{
    "data": [
        {
            "id": 1,
            "name": "Lisboa",
            "mapPositionLat": 38.744109384274,
            "mapPositionLng": -9.1612243652344,
            "mapPositionZoom": 10,
            "description": ""
        },
        {
            "id": 2,
            "name": "Porto -pt",
            "mapPositionLat": 24.906367237908,
            "mapPositionLng": 5.9765625,
            "mapPositionZoom": 1,
            "description": ""
        },
        {
            "id": 3,
            "name": "Lagos",
            "mapPositionLat": 38.048091067457,
            "mapPositionLng": -7.3828125,
            "mapPositionZoom": 1,
            "description": ""
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_items": 3,
        "per_page": 10,
        "total_pages": 1
    }
}
```


## Get City detail ##

### GET - api/v1/cities/{id}

Path parameters: 

* id - ❗required

#### Example request: 
api/v1/cities/6

##### Response:

```json
{
    "data": {
        "id": 6,
        "name": "Coimbra",
        "mapPositionLat": 36.368221900851,
        "mapPositionLng": -89.6484375,
        "mapPositionZoom": 1,
        "description": null
    }
}
```