URL Data

Load data from external URLs. Supports JSON and CSV endpoints.

---

Basic Usage

```dg
type: line
data:
  url: "https://api.example.com/metrics.json"
x: date
y: value
title: Live Metrics
```

---

Supported Formats

DataGlass auto-detects format from:

1. Content-Type header
2. File extension in URL
3. Response content analysis

Format	Content-Type	Extension
JSON	application/json	.json
CSV	text/csv	.csv

---

JSON API Response

Most APIs return JSON. DataGlass handles common response structures:

Array of objects:

[
  {"date": "2024-01-01", "value": 100},
  {"date": "2024-01-02", "value": 150}
]

Object with data property:

{
  "data": [
    {"date": "2024-01-01", "value": 100}
  ],
  "meta": {"total": 1}
}

DataGlass extracts the array from data, results, or items properties.

---

CSV Endpoints

```dg
type: bar
data:
  url: "https://example.com/report.csv"
x: category
y: value
```

---

Public Data Sources

Some useful public APIs:

GitHub API:

data:
  url: "https://api.github.com/repos/owner/repo/stats/commit_activity"

World Bank:

data:
  url: "https://api.worldbank.org/v2/country/all/indicator/NY.GDP.MKTP.CD?format=json"

---

Caching

URL data is cached to improve performance:

• Default TTL: 5 minutes
• Cache stored in memory
• Refresh on Obsidian reload

Configure in Settings > DataGlass:

• cacheEnabled: Enable/disable caching
• cacheTTL: Cache duration in milliseconds

---

Security Considerations

DataGlass applies security restrictions:

Setting	Default	Description
HTTPS preferred	Yes	HTTP upgrades to HTTPS
Localhost blocked	Yes	Local servers blocked by default
URL whitelist	None	Optional allowed domains

Configure security in src/config/security-config.ts for custom deployments.

---

Complete Example

```dg
type: line
data:
  url: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/4.5_week.geojson"
x: properties.time
y: properties.mag
title: Recent Earthquakes (M4.5+)
marks:
  - type: dot
```

---

Handling Nested Data

If your API returns nested objects, use transformations:

data:
  url: "https://api.example.com/nested"
transformations:
  - type: derive
    configuration:
      columns:
        timestamp: "properties.time"
        magnitude: "properties.mag"

---

Tips

Rate Limits: Be mindful of API rate limits. Use caching to reduce requests.

CORS: Some APIs block browser requests. Use a CORS proxy or contact the API provider.

Authentication: For APIs requiring auth, consider fetching data to a local file first.

---

Common Mistakes

Wrong: HTTP without quotes

data:
  url: http://example.com/data.json  # YAML interprets : as special

Right: Quote URLs

data:
  url: "https://example.com/data.json"

Wrong: Expecting auth to work

data:
  url: "https://api.private.com/data"  # Likely 401 error

---

See Also

• File Data - Load from vault files
• Inline Data - Embed data directly
• Transformations - Process API responses