103 lines
1.9 KiB
Markdown
103 lines
1.9 KiB
Markdown
# 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>,
|
|
},
|
|
...
|
|
],
|
|
}
|
|
```
|