Logs API

The Logs API provides access to change logs and activity history for waypoints. These logs track all actions taken on waypoints including creation, edits, approvals, and deletions.

Endpoints

GET /api/logs

Get all change logs in the system with optional filtering.

Authentication: Not required

Query Parameters:

bubblerId (number, optional) - Filter logs by waypoint ID
userId (string, optional) - Filter logs by user ID who performed the action
action (string, optional) - Filter by action type (created, edited, approved, verified, deleted)
limit (number, optional) - Number of logs to return (default: 50, max: 100)
offset (number, optional) - Pagination offset (default: 0)

Example Requests:

Get all recent logs:

curl https://bubblymaps.org/api/logs

Get logs for a specific waypoint:

curl "https://bubblymaps.org/api/logs?bubblerId=42"

Get logs for a specific user:

curl "https://bubblymaps.org/api/logs?userId=user123"

Get logs by action type:

curl "https://bubblymaps.org/api/logs?action=approved"

Response:

{
  "logs": [
    {
      "id": 156,
      "bubblerId": 42,
      "userId": "user123",
      "action": "created",
      "changes": {
        "name": "Bryant Park Fountain",
        "latitude": 40.7536,
        "longitude": -73.9832
      },
      "timestamp": "2024-01-20T15:45:00Z"
    },
    {
      "id": 157,
      "bubblerId": 42,
      "userId": "user456",
      "action": "edited",
      "changes": {
        "description": "Modern fountain with cold water"
      },
      "timestamp": "2024-01-21T09:30:00Z"
    },
    {
      "id": 158,
      "bubblerId": 42,
      "userId": "moderator789",
      "action": "approved",
      "changes": {
        "approved": true
      },
      "timestamp": "2024-01-21T10:00:00Z"
    }
  ],
  "total": 2341,
  "limit": 50,
  "offset": 0
}

Error Responses:

400 Bad Request - Invalid query parameters
500 Internal Server Error - Failed to fetch logs

GET /api/logs/[id]

Get a specific log entry by its ID.

Authentication: Not required

URL Parameters:

id (number) - Log entry ID

Example Request:

curl https://bubblymaps.org/api/logs/156

Response:

{
  "log": {
    "id": 156,
    "bubblerId": 42,
    "userId": "user123",
    "action": "created",
    "changes": {
      "name": "Bryant Park Fountain",
      "latitude": 40.7536,
      "longitude": -73.9832,
      "description": "Modern fountain in the park",
      "region": "Manhattan"
    },
    "timestamp": "2024-01-20T15:45:00Z",
    "user": {
      "id": "user123",
      "name": "John Doe",
      "level": 8
    },
    "waypoint": {
      "id": 42,
      "name": "Bryant Park Fountain",
      "latitude": 40.7536,
      "longitude": -73.9832
    }
  }
}

Error Responses:

404 Not Found - Log entry does not exist
500 Internal Server Error - Failed to fetch log

GET /api/logs/recent

Get the most recent activity logs across the platform.

Authentication: Not required

Query Parameters:

limit (number, optional) - Number of logs to return (default: 20, max: 50)

Example Request:

curl "https://bubblymaps.org/api/logs/recent?limit=10"

Response:

{
  "logs": [
    {
      "id": 2450,
      "bubblerId": 89,
      "userId": "user999",
      "action": "created",
      "changes": {
        "name": "Central Square Fountain"
      },
      "timestamp": "2024-01-23T14:30:00Z",
      "user": {
        "name": "Alice Johnson"
      },
      "waypoint": {
        "name": "Central Square Fountain"
      }
    },
    {
      "id": 2449,
      "bubblerId": 42,
      "userId": "user456",
      "action": "edited",
      "changes": {
        "verified": true
      },
      "timestamp": "2024-01-23T14:15:00Z",
      "user": {
        "name": "Bob Smith"
      },
      "waypoint": {
        "name": "Bryant Park Fountain"
      }
    }
  ],
  "total": 10
}

Error Responses:

400 Bad Request - Invalid query parameters
500 Internal Server Error - Failed to fetch recent logs

Data Model

Log Object

Field	Type	Description
`id`	number	Unique log entry identifier
`bubblerId`	number	ID of the waypoint this log relates to
`userId`	string	ID of the user who performed the action
`action`	string	Type of action performed
`changes`	object	Object containing the changed fields
`timestamp`	string	When the action occurred (ISO 8601)
`user`	object	(Optional) User information object
`waypoint`	object	(Optional) Waypoint information object

Action Types

The following action types are tracked in the logs:

Action	Description
`created`	Waypoint was created
`edited`	Waypoint information was modified
`approved`	Waypoint was approved by a moderator
`verified`	Waypoint was marked as verified
`deleted`	Waypoint was deleted
`unapproved`	Waypoint approval was revoked
`unverified`	Waypoint verification was revoked

Changes Object

The changes object contains the fields that were modified in the action. For example:

Create action:

{
  "name": "New Fountain",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "description": "A new water fountain"
}

Edit action:

{
  "description": "Updated description",
  "verified": true
}

Approval action:

{
  "approved": true
}

Usage Examples

JavaScript/Fetch - Get Waypoint History

async function getWaypointHistory(bubblerId) {
  const response = await fetch(
    `https://bubblymaps.org/api/logs?bubblerId=${bubblerId}`
  );
  
  if (!response.ok) {
    throw new Error('Failed to fetch logs');
  }
  
  const data = await response.json();
  return data.logs;
}

// Usage
getWaypointHistory(42)
  .then(logs => {
    logs.forEach(log => {
      console.log(`${log.timestamp}: ${log.action} by ${log.userId}`);
    });
  })
  .catch(error => console.error('Error:', error));

JavaScript/Fetch - Get Recent Activity Feed

async function getRecentActivity(limit = 20) {
  const response = await fetch(
    `https://bubblymaps.org/api/logs/recent?limit=${limit}`
  );
  
  if (!response.ok) {
    throw new Error('Failed to fetch recent activity');
  }
  
  const data = await response.json();
  return data.logs;
}

// Usage
getRecentActivity(10)
  .then(logs => {
    console.log('Recent platform activity:');
    logs.forEach(log => {
      console.log(
        `${log.user.name} ${log.action} "${log.waypoint.name}"`
      );
    });
  })
  .catch(error => console.error('Error:', error));

Python - Get User Activity

import requests

def get_user_activity(user_id):
    url = f"https://bubblymaps.org/api/logs?userId={user_id}"
    response = requests.get(url)
    
    if response.status_code == 200:
        return response.json()['logs']
    else:
        raise Exception(f"Failed to fetch user activity: {response.status_code}")

# Usage
activity = get_user_activity('user123')
print(f"User has {len(activity)} logged actions")
for log in activity:
    print(f"- {log['action']} on waypoint {log['bubblerId']} at {log['timestamp']}")

Python - Get Logs by Action Type

import requests
from datetime import datetime

def get_logs_by_action(action, limit=50):
    url = f"https://bubblymaps.org/api/logs?action={action}&limit={limit}"
    response = requests.get(url)
    
    if response.status_code == 200:
        return response.json()['logs']
    else:
        raise Exception(f"Failed to fetch logs: {response.status_code}")

# Usage
approved_logs = get_logs_by_action('approved', limit=10)
print(f"Recent approvals: {len(approved_logs)}")
for log in approved_logs:
    timestamp = datetime.fromisoformat(log['timestamp'].replace('Z', '+00:00'))
    print(f"- Waypoint {log['bubblerId']} approved at {timestamp}")

Python - Get Detailed Log Entry

import requests

def get_log_details(log_id):
    url = f"https://bubblymaps.org/api/logs/{log_id}"
    response = requests.get(url)
    
    if response.status_code == 200:
        return response.json()['log']
    else:
        raise Exception(f"Failed to fetch log details: {response.status_code}")

# Usage
log = get_log_details(156)
print(f"Action: {log['action']}")
print(f"User: {log['user']['name']}")
print(f"Waypoint: {log['waypoint']['name']}")
print(f"Changes: {log['changes']}")

Use Cases

The Logs API is useful for:

Activity Feeds - Display recent platform activity
Audit Trails - Track all changes to waypoints
User Contributions - Show a user's contribution history
Moderation - Review approval and verification actions
Analytics - Analyze platform usage patterns
History Display - Show waypoint edit history
Notifications - Trigger notifications for specific actions
Transparency - Public record of all platform changes

Notes

All logs are publicly accessible
Logs are immutable and cannot be modified or deleted
The system automatically creates log entries for all waypoint actions
Logs older than 2 years may be archived for performance
The changes object only includes fields that were actually modified

Logs API

On this page