# Borderly - Geographic SVG API

> Borderly is a simple URL-based API that generates SVG shapes of any geographic region. No API keys required for basic usage.

## Quick Start

Embed a state or country shape with a simple img tag:

```html
<img src="https://borderly.dev/california.svg" alt="California" />
<img src="https://borderly.dev/country/germany.svg" alt="Germany" />
```

## Base URL

https://borderly.dev

## Supported Regions

### US States
- By abbreviation: `/ca.svg`, `/tx.svg`, `/ny.svg`
- By name: `/california.svg`, `/texas.svg`, `/new-york.svg`
- By FIPS code: `/state/06.svg`, `/state/48.svg`

### Countries (200+)
- By ISO Alpha-2: `/country/us.svg`, `/country/de.svg`, `/country/jp.svg`
- By ISO Alpha-3: `/country/usa.svg`, `/country/deu.svg`
- By name: `/country/germany.svg`, `/country/united-kingdom.svg`

### US DMAs (Designated Market Areas)
- By DMA code: `/dma/501.svg` (New York), `/dma/803.svg` (Los Angeles)

### US ZIP Codes
- By 5-digit ZIP: `/zip/94107.svg`, `/zip/10001.svg`

### Canada
- Provinces: `/ca-province/ontario.svg`, `/ca-province/bc.svg`
- Economic Regions: `/ca-region/3510.svg`

### India
- States: `/in-state/maharashtra.svg`, `/in-state/karnataka.svg`
- Districts: `/in-district/mumbai.svg`

## Customization Parameters

All parameters are optional query string parameters.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| fill | hex | 22c55e | Fill color (without #) |
| stroke | hex | 166534 | Stroke color (without #) |
| strokeWidth | number | 1.5 | Stroke width in pixels |
| bg | hex | transparent | Background color |
| padding | number | 0 | Padding around shape in pixels |
| opacity | number | 1 | Fill opacity (0-1) |
| pattern | string | - | Fill pattern: dots, stripes, crosshatch, grid, waves, zigzag, diamonds, hexagons |
| patternBg | hex | transparent | Pattern background color |
| zoom | number | 1 | Zoom level (1-5) |
| cx | number | 50 | Center X for zoom (0-100) |
| cy | number | 50 | Center Y for zoom (0-100) |
| rotate | number | 0 | Rotation angle in degrees |
| animation | string | - | CSS animation: pulse, glow, float, spin, fade |

## Example URLs

### Basic Usage
```
https://borderly.dev/california.svg
https://borderly.dev/country/france.svg
https://borderly.dev/dma/501.svg
```

### With Customization
```
https://borderly.dev/texas.svg?fill=3b82f6&stroke=1d4ed8
https://borderly.dev/country/japan.svg?fill=ef4444&strokeWidth=2
https://borderly.dev/california.svg?pattern=stripes&fill=22c55e
https://borderly.dev/ny.svg?animation=pulse&fill=8b5cf6
https://borderly.dev/florida.svg?zoom=2&cx=50&cy=50
https://borderly.dev/wa.svg?rotate=45
```

## Geocoding API

Reverse geocode coordinates to find which region contains a point.

### Endpoint
```
GET /api/geocode?lat={latitude}&lng={longitude}
```

### Example
```
GET https://borderly.dev/api/geocode?lat=37.77&lng=-122.42
```

### Response
```json
{
  "coordinates": { "lat": 37.77, "lng": -122.42 },
  "country": { "name": "United States", "iso2": "US", "iso3": "USA" },
  "state": { "name": "California", "fips": "06", "abbrev": "CA" },
  "dma": { "name": "San Francisco-Oakland-San Jose", "code": "807" },
  "zip": { "code": "94102" }
}
```

### Coordinate-Based SVG
You can also get SVGs directly from coordinates:
```
https://borderly.dev/state.svg?lat=37.77&lng=-122.42
https://borderly.dev/country.svg?lat=48.86&lng=2.35
```

## Composite Maps (API Key Required)

Combine multiple regions into a single SVG. Requires a free API key from /dashboard.

```
https://borderly.dev/composite.svg?regions=ca,tx,ny&apikey=YOUR_KEY
```

## Code Examples

### HTML
```html
<img src="https://borderly.dev/california.svg" alt="California" />
```

### React
```jsx
function StateMap({ state, fill = '22c55e' }) {
  return (
    <img 
      src={`https://borderly.dev/${state}.svg?fill=${fill}`}
      alt={`${state} map`}
    />
  );
}
```

### Python (Jupyter)
```python
from IPython.display import Image
display(Image(url='https://borderly.dev/california.svg?fill=3b82f6'))
```

## Response Headers

- `Content-Type: image/svg+xml`
- `Cache-Control: public, max-age=86400` (static) or `max-age=3600` (customized)
- `X-Borderly-Source: static | static-templated | edge-generated`

## Rate Limits

- No rate limits for basic usage
- Composite maps require API key (free tier available)

## Support

- Documentation: https://borderly.dev/docs
- Explorer: https://borderly.dev/explorer
- Status: https://statuspage.incident.io/borderly
- Contact: nour@berkeley.edu

## Links

- Website: https://borderly.dev
- Docs: https://borderly.dev/docs
- Explorer: https://borderly.dev/explorer
- Changelog: https://borderly.dev/changelog