--- openapi: 3.0.1 info: title: API V1 version: v1 paths: "/api/v1/areas": post: summary: Creates an area tags: - Areas parameters: - name: api_key in: query required: true description: API Key schema: type: string responses: '201': description: area created '422': description: invalid request requestBody: content: application/json: schema: type: object properties: name: type: string latitude: type: number longitude: type: number radius: type: number required: - name - latitude - longitude - radius examples: '0': summary: Creates an area value: name: Home latitude: 40.7128 longitude: -74.006 radius: 100 get: summary: Retrieves all areas tags: - Areas parameters: - name: api_key in: query required: true description: API Key schema: type: string responses: '200': description: areas found content: application/json: schema: type: array items: type: object properties: id: type: integer name: type: string latitude: type: number longitude: type: number radius: type: number required: - id - name - latitude - longitude - radius "/api/v1/areas/{id}": delete: summary: Deletes an area tags: - Areas parameters: - name: api_key in: query required: true description: API Key schema: type: string - name: id in: path required: true description: Area ID schema: type: string responses: '200': description: area deleted "/api/v1/countries/visited_cities": get: summary: Get visited cities by date range tags: - Countries description: Returns a list of visited cities and countries based on tracked points within the specified date range parameters: - name: api_key in: query required: true schema: type: string - name: start_at in: query format: date-time required: true description: Start date and time for the range (ISO 8601 format) example: '2023-01-01T00:00:00Z' schema: type: string - name: end_at in: query format: date-time required: true description: End date and time for the range (ISO 8601 format) example: '2023-12-31T23:59:59Z' schema: type: string responses: '200': description: cities found content: application/json: schema: type: object properties: data: type: array description: Array of countries and their visited cities items: type: object properties: country: type: string example: Germany cities: type: array items: type: object properties: city: type: string example: Berlin points: type: integer example: 4394 description: Number of points in the city timestamp: type: integer example: 1724868369 description: Timestamp of the last point in the city in seconds since Unix epoch stayed_for: type: integer example: 24490 description: Number of minutes the user stayed in the city '400': description: bad request - missing parameters content: application/json: schema: type: object properties: error: type: string example: 'Missing required parameters: start_at, end_at' "/api/v1/health": get: summary: Retrieves application status tags: - Health responses: '200': description: Healthy "/api/v1/overland/batches": post: summary: Creates a batch of points tags: - Batches parameters: - name: api_key in: query required: true description: API Key schema: type: string responses: '201': description: Batch of points created '401': description: Unauthorized requestBody: content: application/json: schema: type: object properties: type: type: string geometry: type: object properties: type: type: string coordinates: type: array properties: type: object properties: timestamp: type: string altitude: type: number speed: type: number horizontal_accuracy: type: number vertical_accuracy: type: number motion: type: array pauses: type: boolean activity: type: string desired_accuracy: type: number deferred: type: number significant_change: type: string locations_in_payload: type: number device_id: type: string wifi: type: string battery_state: type: string battery_level: type: number required: - geometry - properties examples: '0': summary: Creates a batch of points value: locations: - type: Feature geometry: type: Point coordinates: - 13.356718 - 52.502397 properties: timestamp: '2021-06-01T12:00:00Z' altitude: 0 speed: 0 horizontal_accuracy: 0 vertical_accuracy: 0 motion: [] pauses: false activity: unknown desired_accuracy: 0 deferred: 0 significant_change: unknown locations_in_payload: 1 device_id: Swagger wifi: unknown battery_state: unknown battery_level: 0 "/api/v1/owntracks/points": post: summary: Creates a point tags: - Points parameters: - name: api_key in: query required: true description: API Key schema: type: string responses: '200': description: Point created '401': description: Unauthorized requestBody: content: application/json: schema: type: object properties: batt: type: number lon: type: number acc: type: number bs: type: number inrids: type: array BSSID: type: string SSID: type: string vac: type: number inregions: type: array lat: type: number topic: type: string t: type: string conn: type: string m: type: number tst: type: number alt: type: number _type: type: string tid: type: string _http: type: boolean ghash: type: string isorcv: type: string isotst: type: string disptst: type: string required: - owntracks/jane examples: '0': summary: Creates a point value: batt: 85 lon: -74.006 acc: 8 bs: 2 inrids: - 5f1d1b BSSID: b0:f2:8:45:94:33 SSID: Home Wifi vac: 3 inregions: - home lat: 40.7128 topic: owntracks/jane/iPhone 12 Pro t: p conn: w m: 1 tst: 1706965203 alt: 41 _type: location tid: RO _http: true ghash: u33d773 isorcv: '2024-02-03T13:00:03Z' isotst: '2024-02-03T13:00:03Z' disptst: '2024-02-03 13:00:03' "/api/v1/photos": get: summary: Lists photos tags: - Photos parameters: - name: api_key in: query required: true schema: type: string - name: start_date in: query required: true description: Start date in ISO8601 format, e.g. 2024-01-01 schema: type: string - name: end_date in: query required: true description: End date in ISO8601 format, e.g. 2024-01-02 schema: type: string responses: '200': description: photos found content: application/json: schema: type: array items: type: object properties: id: type: string latitude: type: number format: float longitude: type: number format: float localDateTime: type: string format: date-time originalFileName: type: string city: type: string state: type: string country: type: string type: type: string enum: - image - video orientation: type: string enum: - portrait - landscape source: type: string enum: - immich - photoprism required: - id - latitude - longitude - localDateTime - originalFileName - city - state - country - type - source "/api/v1/photos/{id}/thumbnail": get: summary: Retrieves a photo tags: - Photos parameters: - name: id in: path required: true schema: type: string - name: api_key in: query required: true schema: type: string - name: source in: query required: true schema: type: string responses: '200': description: photo found content: application/json: schema: type: object properties: id: type: string latitude: type: number format: float longitude: type: number format: float localDateTime: type: string format: date-time originalFileName: type: string city: type: string state: type: string country: type: string type: type: string enum: - IMAGE - VIDEO - image - video - raw - live - animated orientation: type: string enum: - portrait - landscape source: type: string enum: - immich - photoprism '404': description: photo not found "/api/v1/points/tracked_months": get: summary: Returns list of tracked years and months tags: - Points parameters: - name: api_key in: query required: true description: API Key schema: type: string responses: '200': description: years and months found content: application/json: schema: type: array items: type: object properties: year: type: integer description: Year in YYYY format months: type: array items: type: string description: Three-letter month abbreviation required: - year - months example: - year: 2024 months: - Jan - Feb - Mar - Apr - May - Jun - Jul - Aug - Sep - Oct - Nov - Dec '401': description: unauthorized "/api/v1/points": get: summary: Retrieves all points tags: - Points parameters: - name: api_key in: query required: true description: API Key schema: type: string - name: start_at in: query description: Start date (i.e. 2024-02-03T13:00:03Z or 2024-02-03) schema: type: string - name: end_at in: query description: End date (i.e. 2024-02-03T13:00:03Z or 2024-02-03) schema: type: string - name: page in: query required: false description: Page number schema: type: integer - name: per_page in: query required: false description: Number of points per page schema: type: integer - name: order in: query required: false description: Order of points, valid values are `asc` or `desc` schema: type: string responses: '200': description: points found content: application/json: schema: type: array items: type: object properties: id: type: integer battery_status: type: number ping: type: number battery: type: number tracker_id: type: string topic: type: string altitude: type: number longitude: type: number velocity: type: number trigger: type: string bssid: type: string ssid: type: string connection: type: string vertical_accuracy: type: number accuracy: type: number timestamp: type: number latitude: type: number mode: type: number inrids: type: array in_regions: type: array raw_data: type: string import_id: type: string city: type: string country: type: string created_at: type: string updated_at: type: string user_id: type: integer geodata: type: string visit_id: type: string "/api/v1/points/{id}": delete: summary: Deletes a point tags: - Points parameters: - name: api_key in: query required: true description: API Key schema: type: string - name: id in: path required: true description: Point ID schema: type: string responses: '200': description: point deleted "/api/v1/settings": patch: summary: Updates user settings tags: - Settings parameters: - name: api_key in: query required: true description: API Key schema: type: string responses: '200': description: settings updated requestBody: content: application/json: schema: type: object properties: route_opacity: type: number meters_between_routes: type: number minutes_between_routes: type: number fog_of_war_meters: type: number time_threshold_minutes: type: number merge_threshold_minutes: type: number optional: - route_opacity - meters_between_routes - minutes_between_routes - fog_of_war_meters - time_threshold_minutes - merge_threshold_minutes examples: '0': summary: Updates user settings value: settings: route_opacity: 0.3 meters_between_routes: 100 minutes_between_routes: 100 fog_of_war_meters: 100 time_threshold_minutes: 100 merge_threshold_minutes: 100 get: summary: Retrieves user settings tags: - Settings parameters: - name: api_key in: query required: true description: API Key schema: type: string responses: '200': description: settings found content: application/json: schema: type: object properties: settings: type: object properties: route_opacity: type: string meters_between_routes: type: string minutes_between_routes: type: string fog_of_war_meters: type: string time_threshold_minutes: type: string merge_threshold_minutes: type: string required: - route_opacity - meters_between_routes - minutes_between_routes - fog_of_war_meters - time_threshold_minutes - merge_threshold_minutes "/api/v1/stats": get: summary: Retrieves all stats tags: - Stats parameters: - name: api_key in: query required: true description: API Key schema: type: string responses: '200': description: stats found content: application/json: schema: type: object properties: totalDistanceKm: type: number totalPointsTracked: type: number totalReverseGeocodedPoints: type: number totalCountriesVisited: type: number totalCitiesVisited: type: number yearlyStats: type: array items: type: object properties: year: type: integer totalDistanceKm: type: number totalCountriesVisited: type: number totalCitiesVisited: type: number monthlyDistanceKm: type: object properties: january: type: number february: type: number march: type: number april: type: number may: type: number june: type: number july: type: number august: type: number september: type: number october: type: number november: type: number december: type: number required: - year - totalDistanceKm - totalCountriesVisited - totalCitiesVisited - monthlyDistanceKm required: - totalDistanceKm - totalPointsTracked - totalReverseGeocodedPoints - totalCountriesVisited - totalCitiesVisited - yearlyStats servers: - url: http://{defaultHost} variables: defaultHost: default: localhost:3000