--- 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 example: Home description: The name of the area latitude: type: number example: 40.7128 description: The latitude of the area longitude: type: number example: -74.006 description: The longitude of the area radius: type: number example: 100 description: The radius of the area in meters 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 example: 1 description: The ID of the area name: type: string example: Home description: The name of the area latitude: type: number example: 40.7128 description: The latitude of the area longitude: type: number example: -74.006 description: The longitude of the area radius: type: number example: 100 description: The radius of the area in meters 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 example: a1b2c3d4e5f6g7h8i9j0 description: Your API authentication key schema: type: string - name: start_at in: query format: date-time required: true description: Start date in YYYY-MM-DD format example: '2023-01-01' schema: type: string - name: end_at in: query format: date-time required: true description: End date in YYYY-MM-DD format example: '2023-12-31' 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 example: - country: Germany cities: - city: Berlin points: 4394 timestamp: 1724868369 stayed_for: 24490 - city: Munich points: 2156 timestamp: 1724782369 stayed_for: 12450 - country: France cities: - city: Paris points: 3267 timestamp: 1724695969 stayed_for: 18720 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 headers: X-Dawarich-Response: type: string required: true example: Hey, I'm alive! description: Depending on the authentication status of the request, the response will be different. If the request is authenticated, the response will be 'Hey, I'm alive and authenticated!'. If the request is not authenticated, the response will be 'Hey, I'm alive!'. X-Dawarich-Version: type: string required: true example: 1.0.0 description: 'The version of the application, for example: 1.0.0' content: application/json: schema: type: object properties: status: type: string "/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 example: Feature geometry: type: object properties: type: type: string example: Point coordinates: type: array example: - 13.356718 - 52.502397 properties: type: object properties: timestamp: type: string example: '2021-06-01T12:00:00Z' description: Timestamp in ISO 8601 format altitude: type: number example: 0 description: Altitude in meters speed: type: number example: 0 description: Speed in meters per second horizontal_accuracy: type: number example: 0 description: Horizontal accuracy in meters vertical_accuracy: type: number example: 0 description: Vertical accuracy in meters motion: type: array example: - walking - running - driving - cycling - stationary description: 'Motion type, for example: automotive_navigation, fitness, other_navigation or other' activity: type: string example: unknown description: 'Activity type, for example: automotive_navigation, fitness, other_navigation or other' desired_accuracy: type: number example: 0 description: Desired accuracy in meters deferred: type: number example: 0 description: the distance in meters to defer location updates significant_change: type: string example: disabled description: a significant change mode, disabled, enabled or exclusive locations_in_payload: type: number example: 1 description: the number of locations in the payload device_id: type: string example: 'iOS device #166' description: the device id unique_id: type: string example: '1234567890' description: the device's Unique ID as set by Apple wifi: type: string example: unknown description: the WiFi network name battery_state: type: string example: unknown description: the battery state, unknown, unplugged, charging or full battery_level: type: number example: 0 description: the battery level percentage, from 0 to 1 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: 'iOS device #166' unique_id: '1234567890' 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 description: Device battery level (percentage) lon: type: number description: Longitude coordinate acc: type: number description: Accuracy of position in meters bs: type: number description: Battery status (0=unknown, 1=unplugged, 2=charging, 3=full) inrids: type: array description: Array of region IDs device is currently in BSSID: type: string description: Connected WiFi access point MAC address SSID: type: string description: Connected WiFi network name vac: type: number description: Vertical accuracy in meters inregions: type: array description: Array of region names device is currently in lat: type: number description: Latitude coordinate topic: type: string description: MQTT topic in format owntracks/user/device t: type: string description: Type of message (p=position, c=circle, etc) conn: type: string description: Connection type (w=wifi, m=mobile, o=offline) m: type: number description: Motion state (0=stopped, 1=moving) tst: type: number description: Timestamp in Unix epoch time alt: type: number description: Altitude in meters _type: type: string description: Internal message type (usually "location") tid: type: string description: Tracker ID used to display the initials of a user _http: type: boolean description: Whether message was sent via HTTP (true) or MQTT (false) ghash: type: string description: Geohash of location isorcv: type: string description: ISO 8601 timestamp when message was received isotst: type: string description: ISO 8601 timestamp of the location fix disptst: type: string description: Human-readable timestamp of the location fix 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 post: summary: Creates a batch of points tags: - Points parameters: - name: api_key in: query required: true description: API Key schema: type: string responses: '200': description: Batch of points being processed '401': description: Unauthorized requestBody: content: application/json: schema: type: object properties: type: type: string geometry: type: object properties: type: type: string example: Point description: the geometry type, always Point coordinates: type: array items: type: number example: - -122.40530871 - 37.74430413 description: the coordinates of the point, longitude and latitude properties: type: object properties: timestamp: type: string example: '2025-01-17T21:03:01Z' description: the timestamp of the point horizontal_accuracy: type: number example: 5 description: the horizontal accuracy of the point in meters vertical_accuracy: type: number example: -1 description: the vertical accuracy of the point in meters altitude: type: number example: 0 description: the altitude of the point in meters speed: type: number example: 92.088 description: the speed of the point in meters per second speed_accuracy: type: number example: 0 description: the speed accuracy of the point in meters per second course_accuracy: type: number example: 0 description: the course accuracy of the point in degrees track_id: type: string example: 799F32F5-89BB-45FB-A639-098B1B95B09F description: the track id of the point set by the device device_id: type: string example: 8D5D4197-245B-4619-A88B-2049100ADE46 description: the device id of the point set by the device required: - geometry - properties examples: '0': summary: Creates a batch of points value: locations: - type: Feature geometry: type: Point coordinates: - -122.40530871 - 37.74430413 properties: battery_state: full battery_level: 0.7 wifi: dawarich_home timestamp: '2025-01-17T21:03:01Z' horizontal_accuracy: 5 vertical_accuracy: -1 altitude: 0 speed: 92.088 speed_accuracy: 0 course: 27.07 course_accuracy: 0 track_id: 799F32F5-89BB-45FB-A639-098B1B95B09F device_id: 8D5D4197-245B-4619-A88B-2049100ADE46 "/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 example: 0.3 description: the opacity of the route, float between 0 and 1 meters_between_routes: type: number example: 100 description: the distance between routes in meters minutes_between_routes: type: number example: 100 description: the time between routes in minutes fog_of_war_meters: type: number example: 100 description: the fog of war distance in meters 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 example: 0.3 description: the opacity of the route, float between 0 and 1 meters_between_routes: type: string example: 100 description: the distance between routes in meters minutes_between_routes: type: string example: 100 description: the time between routes in minutes fog_of_war_meters: type: string example: 100 description: the fog of war distance in meters 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 "/api/v1/users/me": get: summary: Returns the current user tags: - Users security: - bearer_auth: [] parameters: - name: Authorization in: header required: true description: 'Bearer token in the format: Bearer {api_key}' schema: type: string responses: '200': description: user found servers: - url: http://{defaultHost} variables: defaultHost: default: localhost:3000