Borderly API Documentation

Generate SVG shapes of any country, US state, ZIP code, or DMA with a simple URL. No API keys required for basic usage.

Quick Start

Embed a geographic shape with a simple img tag:

<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

API 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 Request

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

Example Response

{
  "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

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

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

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

Python (Jupyter Notebook)

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

Using an API Key

API keys are optional but enable composite maps and usage tracking. Get a free key at /dashboard.

Via Query Parameter

<img src="https://borderly.dev/california.svg?apikey=YOUR_KEY" alt="California" />

Via HTTP Header (curl)

curl -H "x-api-key: YOUR_KEY" https://borderly.dev/california.svg

Coming Soon

@borderly/react - Official React component library for easier integration
Counties - US county-level shapes
More countries - State/province level data for additional countries

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 & Links

Interactive Explorer: borderly.dev/explorer
Status Page: statuspage.incident.io/borderly
Changelog: borderly.dev/changelog
Contact: [email protected]