# SchoolDigger Widgets - Full Reference

> Embeddable school data widgets for websites. Powered by SchoolDigger.

SchoolDigger Widgets lets developers embed interactive school and district data on any website using simple HTML embed codes. The service provides 8 widget types covering school information, rankings, search, maps, and test scores - all backed by SchoolDigger's comprehensive K-12 school database covering 130,000+ schools across all 50 US states.

---

## Quick Start

1. Sign up at https://widgets.schooldigger.com/signup
2. Add your website domain in the dashboard under Domains
3. Use the widget builder at https://widgets.schooldigger.com/catalog to configure style and options
4. Copy the generated embed code (JavaScript or iframe format)
5. Paste into your HTML and customize `data-*` attributes as needed

---

## Embed Formats

### JavaScript Embed (Recommended)

Uses a container `<div>` with data attributes plus the widget loader script:

```html
<!-- Full example with custom styling -->
<div id="sd-widget-340576000472"
     data-sd-widget="school-info-card"
     data-config="eyJ3aWRn...base64..."
     data-school-id="340576000472"
     data-show-address="true"
     data-show-ranking="true">
</div>
<script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

<!-- Minimal example - default styling, just data attributes -->
<div data-sd-widget="school-info-card"
     data-school-id="340576000472">
</div>
<script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>
```

### Iframe Embed

Uses the same options as URL query parameters:

```html
<!-- Full example with custom styling -->
<iframe
  src="https://widgets.schooldigger.com/embed/school-info-card?config=eyJ3aWRn...&appID=YOUR_APP_ID&schoolId=340576000472&showAddress=true&showRanking=true"
  width="350" height="200" frameborder="0"
  title="SchoolDigger Widget">
</iframe>

<!-- Minimal example - default styling -->
<iframe
  src="https://widgets.schooldigger.com/embed/school-info-card?appID=YOUR_APP_ID&schoolId=340576000472"
  width="350" height="200" frameborder="0"
  title="SchoolDigger Widget">
</iframe>
```

### Configuration Layers

Widgets are configured with two types of attributes:

- **`data-config`** (optional) - A Base64-encoded JSON blob containing style options (colors, fonts, theme, branding, sizing). Generated by the widget builder. If omitted, sensible defaults are used.
- **`data-*` attributes** - Plain-text HTML attributes for all functional options (which school, what to show/hide, search defaults, etc.). Easy to read and modify directly in embed code.

### Attribute Naming

- Data attributes use **kebab-case**: `data-show-address`
- Iframe query parameters use **camelCase**: `showAddress`
- Boolean values accept `"true"` or `"false"`

---

## Widget Reference

### School Info Card

- **Widget ID**: `school-info-card`
- **Minimum tier**: Free
- **Category**: Display
- **Default size**: 350px x 200px (responsive)
- **Description**: Displays school name, address, grades served, contact info, and ranking.

**Required Selections (set in builder):**

| Attribute | Type | Description |
|-----------|------|-------------|
| `data-school-id` | string (School ID) | The SchoolDigger school ID (required) |

**Editable Options:**

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-show-address` | boolean | `true` | Show school address |
| `data-show-phone` | boolean | `true` | Show phone number |
| `data-show-grades` | boolean | `true` | Show grades served |
| `data-show-ranking` | boolean | `true` | Show ranking badge |
| `data-show-type` | boolean | `true` | Show school type |

---

### District Info Card

- **Widget ID**: `district-info-card`
- **Minimum tier**: Free
- **Category**: Display
- **Default size**: 350px x 200px (responsive)
- **Description**: District summary with student count, school counts, and rankings.

**Required Selections (set in builder):**

| Attribute | Type | Description |
|-----------|------|-------------|
| `data-district-id` | string (District ID) | The SchoolDigger district ID (required) |

**Editable Options:**

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-show-address` | boolean | `true` | Show district address |
| `data-show-phone` | boolean | `true` | Show phone number |
| `data-show-ranking` | boolean | `true` | Show ranking |
| `data-show-school-count` | boolean | `true` | Show number of schools |
| `data-show-student-count` | boolean | `true` | Show student enrollment |

---

### Ranking Badge

- **Widget ID**: `ranking-badge`
- **Minimum tier**: Basic
- **Category**: Display
- **Default size**: 200px x 100px (responsive)
- **Description**: Star rating indicator with percentile rank.

**Required Selections (set in builder):**

| Attribute | Type | Description |
|-----------|------|-------------|
| `data-school-id` | string (School ID) | The SchoolDigger school ID (required) |

**Editable Options:**

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-show-stars` | boolean | `true` | Show star rating |
| `data-show-percentile` | boolean | `true` | Show percentile rank |
| `data-show-school-name` | boolean | `true` | Show school name |

---

### School Finder

- **Widget ID**: `school-finder`
- **Minimum tier**: Basic
- **Category**: Search
- **Default size**: 400px x 500px (responsive)
- **Description**: Search schools by address, ZIP code, or city.

**Editable Options:**

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-default-state` | string (2-letter state code) | - | Pre-select a state |
| `data-default-level` | enum | All Levels | `elementary`, `middle`, `high` |
| `data-results-per-page` | string | `10` | Number of results to show |
| `data-show-ranking` | boolean | `true` | Show rankings in results |
| `data-on-school-click` | enum | `navigate` | `navigate` (go to SchoolDigger) or `callback` (postMessage) |

---

### Top Schools List

- **Widget ID**: `top-schools-list`
- **Minimum tier**: Basic
- **Category**: Display
- **Default size**: 400px x 500px (responsive)
- **Description**: Top-ranked schools by state and school level.

**Required Selections (set in builder):**

| Attribute | Type | Description |
|-----------|------|-------------|
| `data-state` | string (2-letter state code) | State to show rankings for (required) |

**Editable Options:**

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-level` | enum | `elementary` | `elementary`, `middle`, `high` |
| `data-count` | string | `10` | Number of schools to show |
| `data-on-school-click` | enum | `navigate` | `navigate` or `callback` |

---

### Autocomplete Search (School)

- **Widget ID**: `school-autocomplete`
- **Minimum tier**: Basic
- **Category**: Search
- **Default size**: 350px x 50px (responsive)
- **Description**: Type-ahead search for schools.

**Editable Options:**

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-placeholder` | string | `Search for a school...` | Input placeholder text |
| `data-on-select-action` | enum | `navigate` | `navigate` or `callback` |

---

### Autocomplete Search (District)

- **Widget ID**: `district-autocomplete`
- **Minimum tier**: Basic
- **Category**: Search
- **Default size**: 350px x 50px (responsive)
- **Description**: Type-ahead search for districts.

**Editable Options:**

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-placeholder` | string | `Search for a district...` | Input placeholder text |
| `data-on-select-action` | enum | `navigate` | `navigate` or `callback` |

---

### Test Score Charts

- **Widget ID**: `test-score-chart`
- **Minimum tier**: Pro
- **Category**: Display
- **Default size**: 450px x 350px (responsive)
- **Description**: Interactive charts showing test scores by subject and year.

**Required Selections (set in builder):**

| Attribute | Type | Description |
|-----------|------|-------------|
| `data-school-id` | string (School ID) | The SchoolDigger school ID (required) |

**Editable Options:**

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-default-subject` | enum | `math` | `math`, `ela` (English Language Arts) |
| `data-show-state-average` | boolean | `true` | Show state average comparison line |
| `data-show-district-average` | boolean | `true` | Show district average comparison |

---

### Nearby Schools Map

- **Widget ID**: `nearby-schools-map`
- **Minimum tier**: Pro
- **Category**: Search
- **Default size**: 500px x 400px (responsive)
- **Description**: Interactive map showing nearby schools with distance filters.

**Required Selections (set in builder):**

| Attribute | Type | Description |
|-----------|------|-------------|
| `data-school-id` | string (School ID) | Center the map on this school (required) |

**Editable Options:**

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-radius` | string | `5` | Search radius in miles |
| `data-default-level` | enum | All Levels | `elementary`, `middle`, `high` |
| `data-show-ranking` | boolean | `true` | Show rankings on map pins |
| `data-on-school-click` | enum | `navigate` | `navigate` or `callback` |

---

## Style Options (data-config)

These options are encoded in the `data-config` Base64 blob, generated by the widget builder. The attribute is optional - defaults are used if omitted.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `primaryColor` | hex color | `#1a73e8` | Main widget accent color |
| `fontFamily` | CSS font stack | system-ui | Font family for widget text |
| `fontSize` | enum | `medium` | `small`, `medium`, or `large` |
| `theme` | enum | `light` | `light` or `dark` |
| `borderRadius` | enum | `medium` | `none`, `small`, `medium`, or `large` |
| `showBranding` | boolean | `true` | Show SchoolDigger attribution (Pro+ to disable) |
| `customCss` | string | - | Custom CSS rules (Enterprise tier only) |

---

## Callback Events

Widgets that support the `callback` action mode communicate via `window.postMessage`.

### sd-school-clicked

Fired when a user clicks a school in school-finder, top-schools-list, or nearby-schools-map (when `data-on-school-click="callback"`).

```javascript
window.addEventListener('message', function(event) {
    if (event.data.type === 'sd-school-clicked') {
        const school = event.data.school;
        // school: { schoolId, schoolName, city, state, zip,
        //           schoolLevel, lowGrade, highGrade,
        //           rank, rankStars, distance, url }
    }
});
```

### sd-school-selected

Fired when a user selects a school from school-autocomplete (when `data-on-select-action="callback"`).

```javascript
window.addEventListener('message', function(event) {
    if (event.data.type === 'sd-school-selected') {
        const school = event.data.school;
        // school: { schoolId, schoolName, city, state,
        //           lowGrade, highGrade, schoolLevel, rankStars }
    }
});
```

### sd-school-cleared

Fired when the school autocomplete selection is cleared.

### sd-district-selected

Fired when a user selects a district from district-autocomplete (when `data-on-select-action="callback"`).

```javascript
window.addEventListener('message', function(event) {
    if (event.data.type === 'sd-district-selected') {
        const district = event.data.district;
        // district: { districtId, districtName, city, state,
        //             lowGrade, highGrade, rankStars }
    }
});
```

### sd-district-cleared

Fired when the district autocomplete selection is cleared.

### sd-widget-resize

Fired when a widget's dimensions change. Automatically handled by the widget loader.

```javascript
window.addEventListener('message', function(event) {
    if (event.data.type === 'sd-widget-resize') {
        console.log('New height:', event.data.height);
    }
});
```

---

## Pricing Plans

### Free - $0/mo
- 1,000 API calls per month (hard cap)
- 1 domain
- Widgets: School Info Card, District Info Card
- SchoolDigger branding required

### Basic - $29/mo
- 10,000 API calls per month (then $0.002/call)
- 1 domain
- Widgets: All Free widgets + Ranking Badge, School Finder, Top Schools List, Autocomplete Search
- Custom colors
- SchoolDigger branding required

### Pro - $99/mo (Most Popular)
- 50,000 API calls per month (then $0.0025/call)
- 3 domains
- All widgets included (including Test Score Charts, Nearby Schools Map)
- Custom colors, branding removal
- Priority support

### Enterprise - $199/mo
- 100,000 API calls per month (then $0.0028/call)
- 5 domains
- All widgets included
- Custom colors, custom CSS, branding removal
- Dedicated support

All paid plans include a 7-day free trial. No credit card required for Free plan.

---

## Domain Whitelisting

Widgets only load on domains registered in your dashboard. Each plan includes a set number of allowed domains:

- Free: 1 domain
- Basic: 1 domain
- Pro: 3 domains
- Enterprise: 5 domains

Manage domains from your dashboard at https://widgets.schooldigger.com/dashboard.

---

## Custom CSS (Enterprise)

Enterprise tier users can inject custom CSS rules. Add CSS in the widget builder's Custom CSS textarea. CSS is injected inside the widget's `<style>` block within the iframe, so rules won't affect the host page.

```css
/* Example: change the school card border and title color */
.sd-school-card { border: 2px solid #ff5722; }
.sd-school-name { color: #1a73e8; }
```

See the full CSS class reference at https://widgets.schooldigger.com/docs/css-reference.

---

## Links

- Website: https://widgets.schooldigger.com
- Documentation: https://widgets.schooldigger.com/docs
- CSS Reference: https://widgets.schooldigger.com/docs/css-reference
- Pricing: https://widgets.schooldigger.com/pricing
- Live Demo: https://widgets.schooldigger.com/demo
- Widget Builder: https://widgets.schooldigger.com/catalog
- Sign Up: https://widgets.schooldigger.com/signup
- Contact: https://widgets.schooldigger.com/contact
- Privacy Policy: https://widgets.schooldigger.com/privacy
- Terms of Service: https://widgets.schooldigger.com/terms
- SchoolDigger API: https://developer.schooldigger.com