User Stats API #

The User Stats API provides comprehensive statistics about Project Sidewalk users and their contributions in 伊利諾州芝加哥, including labels placed, distance explored, and validation activities. Each user is identified by an anonymized ID, which persists over time.

User Stats API Preview #

Below is a live preview of user statistics in 伊利諾州芝加哥 retrieved directly from the API, showing the distribution of user contributions and label accuracy.

Endpoint#

Retrieve statistics for all registered users or filter based on specific criteria. See Query Parameters below.

GET /v3/api/userStats

Quick Download #

Download user statistics data directly in your preferred format:

Query Parameters#

This endpoint accepts the following optional query parameters.

Responses#

Success Response (200 OK)#

On success, the API returns an HTTP 200 OK status code and the requested data in the specified filetype format.

JSON Format (Default) #

Returns an array of user statistics objects, each representing a single user's contribution data:

[
    {
        "user_id": "bfab6670-0955-440c-abe8-01c2d20696ba",
        "labels": 27,
        "meters_explored": 154.8437957763672,
        "labels_per_meter": 0.17436927556991577,
        "high_quality": true,
        "high_quality_manual": null,
        "label_accuracy": 0.9545454382896423,
        "validated_labels": 22,
        "validations_received": 22,
        "labels_validated_correct": 21,
        "labels_validated_incorrect": 1,
        "labels_not_validated": 5,
        "validations_given": 20,
        "dissenting_validations_given": 5,
        "agree_validations_given": 14,
        "disagree_validations_given": 6,
        "unsure_validations_given": 0,
        "stats_by_label_type": {
            "curb_ramp": {
            "labels": 16,
            "validated_correct": 15,
            "validated_incorrect": 1,
            "not_validated": 0
            },
            "no_curb_ramp": {
                "labels": 0,
                "validated_correct": 0,
                "validated_incorrect": 0,
                "not_validated": 0
            },
            // ... other label types
        }
    },
    // ... more user statistics objects
]

JSON Field Descriptions #

Each user statistics object contains the following fields:

Label Type Statistics Fields #

The stats_by_label_type object contains a key for each label type, with values that provide detailed statistics for that specific type of label:

CSV Format #

If filetype=csv is specified, the response body will be CSV data. The first row contains the header fields, with the stats_by_label_type object flattened into individual columns for each label type and statistic.

user_id,labels,meters_explored,labels_per_meter,high_quality,high_quality_manual,label_accuracy,validated_labels,...
bfab6670-0955-440c-abe8-01c2d20696ba,27,154.8437957763672,0.17436927556991577,true,,0.9545454382896423,22,...
814f4169-98a1-4afa-80da-3b46be1da405,687,9898.09765625,0.06940727680921555,true,,0.8013029098510742,614,...
...

CSV Column Descriptions #

In CSV format, each row corresponds to a user, and the columns map to the JSON fields as follows:

• The first set of columns match the top-level attributes from the JSON format (e.g., user_id, labels, meters_explored, etc.)
• The label type statistics are flattened into a set of columns for each label type, with the naming pattern [label_type]_[statistic]
• For example, curb_ramp_labels, curb_ramp_validated_correct, curb_ramp_validated_incorrect, curb_ramp_not_validated, etc.
• This flattened structure makes it easier to import the data into spreadsheet applications and data analysis tools

Error Responses#

If an error occurs, the API will return an appropriate HTTP status code and a JSON response body containing details about the error.

• 400 Bad Request: Invalid parameter values.
• 404 Not Found: The requested resource does not exist.
• 500 Internal Server Error: An unexpected error occurred on the server.
• 503 Service Unavailable: The server is temporarily unable to handle the request.

Error Response Body #

Error responses include a JSON body with the following structure:

{
    "status": 400, // HTTP Status Code
    "code": "INVALID_PARAMETER", // Machine-readable error code
    "message": "Invalid value for filetype parameter. Expected 'csv' or 'json'.", // Human-readable description
    "parameter": "filetype" // Optional: The specific parameter causing the error
}

Data Analysis Tips #

The User Stats API provides rich data for analysis. Here are some tips for meaningful analysis:

• Consider using minimum thresholds for label count and validated labels to ensure sufficient data for meaningful analysis
• Look beyond just quantity - high label counts don't always equate to high-quality data
• Analyze the relationship between labels per meter and accuracy to understand contribution thoroughness
• Compare validation patterns across different types of labels to identify where quality issues might exist
• Use the Label Types API to get proper color coding and descriptions for visualizations

Contribute#

Project Sidewalk is an open-source project created by the Makeability Lab and hosted on GitHub. We welcome your contributions! If you found a bug or have a feature request, please open an issue on GitHub.

You can also email us at sidewalk@cs.uw.edu

Project Sidewalk in Your City!#

If you are interested in bringing Project Sidewalk to your city, please read our Wiki page.