# API EXTENSIONS FOR MANIPULATING LOCATIONS RECORDS

## NOMENCLATURE

Values enclosed with `<>` are _required_.

Values enclosed with `[]` means _optional_.

No enclosure means _literal_.

## ADDED METHODS

Endpoints _added_ are found under /api/ext/

### `/api/ext/geolocation/`

#### **POST**

Adds a location entry to the database

Request payload:
```
{
	common_name: <string>,
	latitude: <float>,
	longitude: <float>,
	parent_id: [uint],
}

```

`parent_id` is the location table id of the location record for the greater area encapsulating the location being registered.

### `/api/ext/geolocation/<path_string>/`

#### **GET**

Retrieves a location record based on the given `path_string`. Every part of the given path string must match the value in the location hierarchy. A path string must have minimum one part.

Example, given database has `foo/bar` and `foo/baz`: A search of `foo/bar` will only match `foo/bar`. A search of `foo` will match both `foo/bar` and `foo/baz`.

Response payload:

```
{
	id: <uint>,
	common_name: <string>,
	path: <string>,
	latitude: <float>,
	longitude: <float>,
}

```

`common_name` is the location leaf name.

`path` is the full hierarchical path string.

### `/api/ext/geolocation/<ext_type>/<ext_id>/`


#### **GET**

Queries the `location_external` table for a matching value, and returns the `location` object associated with it. 

Currently only `OSM` is supported as `ext_type`. The value given matches a `place_id` entry in the external table.

Data format returned the same as `GET /api/ext/geolocation/<path_string>/`

### `/api/ext/user/<user_id>/geolocation/`

#### **PUT**

Sets the location of the affected user

Data payload:

```
{
	location_id: <uint>
}
```

#### **GET**

Retrieves full objects for the hierarchical path of the user location.

Response payload:

```
{
	user_id: user_id,
	location: [
		{
			common_name: <string>,
			longitude: <float>,
			latitude: <float>,
		},
		...
	],
}
```