UrbanReflex Documentation

Everything you need to build with UrbanReflex platform

Introduction

Welcome to UrbanReflex documentation. This guide will help you integrate our platform into your applications and make the most of our road network and community reporting features.

Note: Our API is currently in beta. Features and endpoints may change.

Quick Start

Get started with UrbanReflex in just a few minutes.

npm install @urbanreflex/sdk
import { UrbanReflex } from '@urbanreflex/sdk';

const client = new UrbanReflex({
  apiKey: 'your-api-key'
});

// Fetch road segments
const roads = await client.roads.list();

Installation

Multiple ways to integrate UrbanReflex into your project.

NPM

npm install @urbanreflex/sdk

Yarn

yarn add @urbanreflex/sdk

Direct API Access

You can also access our API directly without SDK:

curl https://api.urbanreflex.com/api/ngsi-ld?type=RoadSegment&limit=10

Authentication

All API requests require authentication using an API key.

Getting your API Key

  1. Sign in to your UrbanReflex account
  2. Navigate to Settings → API Keys
  3. Click "Generate New Key"
  4. Copy and securely store your key

API Endpoints

API v1 - Public API

Latest

Main API for accessing NGSI-LD data with powerful features: timeframe filtering, entity selection, and date range queries.

GET/api/v1/{apiKey}

Authentication

API key is placed directly in the URL path. Format: ur_xxxxxxxxxxxxx

GET /api/v1/ur_YOUR_API_KEY_HERE

Note: API key must start with ur_. You can create a new API key on the Profile → API Keys page.

Query Parameters

Timeframe
timeframe

Choose how to retrieve data by time:

latest- Get latest data

WeatherObserved: 1 latest record | AirQualityObserved: 1 latest record for each station (10 stations)

alltime- Get all data (default)
custom- Filter by time range

Requires: startDate and/or endDate (ISO 8601 format)

Entity Selection
entities

Select specific entity types to retrieve (comma-separated):

Static Data

Static Data
  • RoadSegment(~5,000)
  • Streetlight(~17,500)
  • PointOfInterest

Dynamic Data

Dynamic Data
  • WeatherObserved(1 OWM)
  • AirQualityObserved(10 OpenAQ)
  • CitizenReport
  • RoadReport
Other Parameters
type

Single entity type (legacy, use entities instead)

limit

Number of items per page (max: 1000, default: 1000)

offset

Offset for pagination

options

Format options (keyValues, etc.)

startDate

Start date (ISO 8601, for custom timeframe)

endDate

End date (ISO 8601, for custom timeframe)

unwrapped

Return array directly (backward compatibility)

Examples

1

Get latest data for all types

GET /api/v1/ur_YOUR_API_KEY?timeframe=latest
2

Get only latest WeatherObserved

GET /api/v1/ur_YOUR_API_KEY?entities=WeatherObserved&timeframe=latest
3

Get only CitizenReport (all)

GET /api/v1/ur_YOUR_API_KEY?entities=CitizenReport&timeframe=alltime
4

Get latest OpenAQ and OWM

GET /api/v1/ur_YOUR_API_KEY?entities=WeatherObserved,AirQualityObserved&timeframe=latest
5

Get CitizenReport in November 2025

GET /api/v1/ur_YOUR_API_KEY?entities=CitizenReport&timeframe=custom&startDate=2025-11-01T00:00:00Z&endDate=2025-11-30T23:59:59Z
6

Get all RoadSegment and Streetlight

GET /api/v1/ur_YOUR_API_KEY?entities=RoadSegment,Streetlight&timeframe=alltime

Response Format

Wrapped Format

Default

Used when timeframe or entities parameter is present

{
  "success": true,
  "data": [
    // Array of entities
  ],
  "meta": {
    "total": 100,
    "types": ["WeatherObserved", "AirQualityObserved"],
    "timeframe": "latest",
    "startDate": null,
    "endDate": null,
    "timestamp": "2025-12-03T10:00:00.000Z"
  }
}

Unwrapped Format

Backward Compatible

Returns array directly, compatible with old code

[
  // Array of entities directly
]

Add ?unwrapped=true to use this format

POST/api/reports

Submit community reports

Request Body

{
  "location": {
    "type": "Point",
    "coordinates": [106.629664, 10.823099]
  },
  "description": "Pothole on main road",
  "category": "road_damage",
  "images": ["url1", "url2"]
}

Rate Limits

API rate limits to ensure fair usage for all users.

Current Limits

Free Tier
1,000
requests/day
With API Key
10,000
requests/day

Rate Limit Headers

Every API response includes rate limit information:

  • X-RateLimit-Limit - Maximum requests allowed
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Time when limit resets

Error Codes

Understanding API error responses.

400 Bad Request

Invalid request parameters or malformed JSON

401 Unauthorized

Missing or invalid API key

429 Too Many Requests

Rate limit exceeded. Wait before making more requests

500 Internal Server Error

Server error. Please try again later or contact support

Example Error Response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 3600 seconds.",
    "statusCode": 429
  }
}

Road Data

Access detailed road network information including segments, properties, and metadata.

Road Segment Properties

  • name: Road name or identifier
  • roadType: Classification (primary, secondary, tertiary, residential)
  • length: Segment length in meters
  • laneCount: Number of lanes
  • surface: Road surface type (asphalt, concrete, etc.)
  • location: GeoJSON LineString coordinates

Example: Fetch roads by type

// Fetch primary roads
const response = await fetch(
  'https://api.urbanreflex.com/api/ngsi-ld?type=RoadSegment&roadType=primary&limit=20'
);
const roads = await response.json();

// Filter by location (within bounds)
roads.filter(road => {
  const coords = road.location.coordinates;
  return isWithinBounds(coords, myBounds);
});

Community Reports

Enable users to submit and view road issue reports.

Report Categories

• road_damage (potholes, cracks)
• traffic_issue (congestion, accidents)
• safety_concern (missing signs, lighting)
• maintenance_needed (debris, flooding)

Example: Submit a report

const report = {
  location: {
    type: "Point",
    coordinates: [106.629664, 10.823099]
  },
  description: "Large pothole causing vehicle damage",
  category: "road_damage",
  severity: "high",
  images: [imageFile1, imageFile2]
};

const response = await fetch('https://api.urbanreflex.com/api/reports', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify(report)
});

Real-time Updates

Subscribe to real-time data updates using WebSocket connections.

⚡ WebSocket API

Connect to: wss://api.urbanreflex.com/ws

Receive instant notifications when new reports are submitted or road data is updated.

Example: WebSocket connection

const ws = new WebSocket('wss://api.urbanreflex.com/ws');

ws.onopen = () => {
  // Subscribe to updates in a specific area
  ws.send(JSON.stringify({
    action: 'subscribe',
    channel: 'reports',
    filter: {
      bounds: {
        north: 10.9,
        south: 10.7,
        east: 106.8,
        west: 106.6
      }
    }
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('New report:', data);
  // Update your UI with new report
};

Platform Overview

UrbanReflex is a comprehensive platform for urban road network data and community reporting.

Key Features

  • ✓Road Network Visualization: Interactive map with detailed road segments
  • ✓Community Reporting: Real-time issue reporting and tracking
  • ✓Open Data: Free access to road infrastructure data
  • ✓RESTful API: Easy integration with your applications

Examples

Common use cases and code examples.

Fetch Road Data

Retrieve road segments within a specific area

View Example

Submit Reports

Allow users to report road issues

View Example

SDKs & Libraries

Official and community-maintained SDKs for different programming languages.

📦

JavaScript/TypeScript

Official SDK

npm install @urbanreflex/sdk
View on GitHub →
🐍

Python

Coming Q1 2025

pip install urbanreflex
In development
💎

Ruby

Community SDK

gem install urbanreflex
View on GitHub →
🎯

Go

Community SDK

go get github.com/urbanreflex/go-sdk
View on GitHub →

Want to contribute?

We welcome community contributions! If you'd like to create an SDK for another language, check out our SDK guidelines on GitHub.