Custom Points in OSW

Custom Points in OSW⚓︎

This guide shows how to add custom non-routable point features (like bus stops) to an OpenSidewalks dataset using the Custom Points entity type.

For a list of all guides on the TCAT Wiki, refer to the Guides List.

What are Custom Points?⚓︎

Custom Points in OpenSidewalks are user-defined non-routable point features that extend the schema beyond the predefined Core Entities and Adjacent Entities point types. While OpenSidewalks includes many built-in point types like fire hydrants, benches, and street lamps, Custom Points let you add any custom feature!

Doing so is simple - just prefix ext: before the tags that are not in the OSW schema.

This approach allows for immediately adding custom data, preserving data from existing systems.

Common Use Cases⚓︎

Custom Points are perfect for adding:

• Transit infrastructure: Bus stops, public transport shelters
• Accessibility features: Accessible parking spaces, wheelchair-accessible entrances, elevators
• Wayfinding aids: Information kiosks, signage
• Points of interest: Water fountains, ATMs, restrooms

Case Study: GTFS Bus Stops to OSW Custom Points⚓︎

In this example, we'll convert bus stop data from a GTFS stops.txt file into OpenSidewalks Custom Points. This is a common scenario for transit agencies and cities wanting to integrate public transportation data with pedestrian network information.

Understanding the Source Data⚓︎

A typical GTFS stops.txt file contains bus stop information like this:

stop_id,stop_code,stop_name,stop_desc,stop_lat,stop_lon,zone_id,stop_url,location_type,parent_station
1001,1001,Main St & 1st Ave,Northbound stop,47.6062,-122.3321,,http://example.com/stops/1001,0,
1002,1002,Main St & 2nd Ave,Southbound stop,47.6065,-122.3325,,http://example.com/stops/1002,0,

The Target: OSW Custom Points⚓︎

We want to convert each bus stop into an OpenSidewalks Custom Point that looks like this:

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [-122.3321, 47.6062]
    },
    "properties": {
        "_id": "bus_stop_1001",
        "ext:stop_id": "1001",
        "ext:stop_code": "1001",
        "ext:stop_name": "Main St & 1st Ave",
        "ext:stop_desc": "Northbound stop",
        "ext:stop_url": "http://example.com/stops/1001"
    }
}

Step-by-Step Conversion Process⚓︎

Step 1: Prepare Your Data⚓︎

Start with your GTFS stops.txt file. You'll need these key fields:

• stop_lat and stop_lon (for coordinates)
• stop_id (for unique identification)
• Any other fields you want to preserve (name, description, etc.)

Quality check your data:

• Remove any stops with missing coordinates
• Ensure stop_id values are unique
• Verify coordinates are in decimal degrees (WGS84)

Step 2: Map Fields to OSW Structure⚓︎

Create a mapping between your GTFS fields and OSW Custom Point properties:

A note on the _id field: Every OSW entity needs a unique _id (string with at least one character). For bus stops, consider using a prefix like "bus_stop_" + the original stop_id to avoid conflicts with other features. Letters, numbers, and underscores are all fine!

Step 3: Create the GeoJSON Structure⚓︎

• Required fields like _id go directly in properties
• Custom fields get the ext: prefix and go in properties
• Geometry goes in the geometry section, not properties

Your Custom Points need to be formatted as GeoJSON Features within a FeatureCollection. Here's how the field mapping from Step 2 translates into actual JSON:

{
    "$schema": "https://sidewalks.washington.edu/opensidewalks/0.3/schema.json",
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [-122.3321, 47.6062] // stop_lon, stop_lat
            },
            "properties": {
                "_id": "bus_stop_1001", // Required OSW field
                "ext:stop_id": "1001", // Original GTFS stop_id
                "ext:stop_name": "Main St & 1st Ave", // Original GTFS stop_name
                "ext:stop_desc": "Northbound stop" // Original GTFS stop_desc
            }
        }
    ]
}

Key Structure Points:

• All of the GTFS data fields (except coordinates) go in the properties section
• Custom fields like ext:stop_name are the actual field names in your JSON
• The ext: prefix is part of the field name, not a folder structure

Step 4: Add Dataset Metadata⚓︎

Include required OpenSidewalks metadata at the dataset level:

{
    "$schema": "https://sidewalks.washington.edu/opensidewalks/0.3/schema.json",
    "type": "FeatureCollection",
    "dataSource": {
        "name": "Metro Transit GTFS",
        "license": "Public Domain"
    },
    "dataTimestamp": "2024-12-01T00:00:00Z",
    "features": [
        // ... your custom points here
    ]
}

Conversion Tools⚓︎

Option 1: Purpose-built Scripts⚓︎

In the specific case of GTFS stops, a script such as this one created by TCAT, gtfs-to-tdei-converter.ps1, can be used.

Option 2: Online JSON Tools⚓︎

Use your spreadsheet software of choice to add ext: prefix to column headers, then convert CSV to GeoJSON:

• https://geojson.io/
• https://mapbox.github.io/csv2geojson/

Validation and Quality Assurance⚓︎

Check Your Output⚓︎

Before using your Custom Points, verify:

1. Valid GeoJSON: Use geojson.io or a JSON validator
2. Coordinate format: Longitude first, then latitude
3. Unique IDs: Each _id appears only once
4. Required fields: Every Custom Point has an _id and valid coordinates
5. Custom fields: All additional data uses the ext: prefix

Common Issues and Fixes⚓︎

Integration with Existing OSW Data⚓︎

Manual Adding to Existing Datasets⚓︎

To add Custom Points to an existing OpenSidewalks dataset:

1. Load your existing .osw file
2. Add your Custom Point features to the features array
3. Ensure all _id values remain unique across the entire dataset

Coordinate System Compatibility⚓︎

OpenSidewalks uses WGS84 (EPSG:4326) coordinates in decimal degrees. GTFS data is already in this format, so no conversion is needed. If your source data uses a different coordinate system, you'll need to reproject it first.

Best Practices⚓︎

Fields⚓︎

• Use descriptive ext: field names: ext:stop_name not ext:name
• Keep original field names when possible for easier maintenance
• Be consistent across all your Custom Points
• Remove unnecessary fields to keep file sizes manageable