Sprime API Documentation

Quick Start

All requests require an API key in the header:

curl -H "x-api-key: your_api_key_here" \
  "https://sprime.us/v1/weather?location=miami"

Base URL: https://sprime.us/v1

Use GET /v1/endpoints to see which endpoints are available on your plan.

Weather API Free

GET/v1/weather

Current weather conditions by city name or coordinates.

Parameter	Type	Required	Description
`location`	string	required*	City name (e.g., "miami", "tokyo")
`lat`	number	required*	Latitude (-90 to 90). Use with lon instead of location.
`lon`	number	required*	Longitude (-180 to 180)
`format`	string	optional	fahrenheit, kelvin (default: celsius)
`enriched`	boolean	optional	Include sunrise, sunset, UV index, wind direction
`fields`	string	optional	Comma-separated fields to return (e.g., "temp,windspeed")
`fresh`	boolean	optional	Skip cache, fetch live data

* Provide either location or both lat and lon

{
  "status": "success",
  "data": {
    "temp": 26.4,
    "condition": 2,
    "windspeed": 12.3,
    "location": "Miami, United States",
    "unit": "celsius"
  },
  "source": "open-meteo",
  "timestamp": "2026-02-06T15:30:00Z"
}

GET/v1/weather/auto

Auto-detect location from your IP address and return local weather.

Crypto API Free

GET/v1/crypto

Real-time cryptocurrency prices and market data.

Parameter	Type	Required	Description
`symbol`	string	required	Ticker (BTC, ETH, SOL) or CoinGecko ID
`convert`	string	optional	Additional currency conversion (EUR, GBP)
`history`	string	optional	Sparkline period: 7d or 30d
`fields`	string	optional	Comma-separated fields to return

{
  "status": "success",
  "data": {
    "symbol": "BTC",
    "price": 97250.18,
    "change_24h": 2.31,
    "market_cap": 1920000000000
  },
  "source": "coingecko",
  "timestamp": "2026-02-06T15:30:00Z"
}

GET/v1/crypto/trending Free

Currently trending cryptocurrencies.

Parameter	Type	Required	Description
`limit`	integer	optional	Number of results (1-50, default: 10)

GET/v1/crypto/rankings Free

Market cap rankings.

Parameter	Type	Required	Description
`limit`	integer	optional	Results per page (1-100, default: 10)
`page`	integer	optional	Page number (default: 1)

GET/v1/crypto/history Free

Historical price for a specific date.

Parameter	Type	Required	Description
`symbol`	string	required	Ticker or CoinGecko ID
`date`	string	required	Date in YYYY-MM-DD format

News API Free

GET/v1/news

Aggregated news headlines from multiple sources.

Parameter	Type	Required	Description
`category`	string	optional	general, business, technology, sports, entertainment, health, science
`sentiment`	boolean	optional	Add sentiment analysis to each article
`fields`	string	optional	Comma-separated fields to return

{
  "status": "success",
  "data": [
    {
      "title": "New AI Breakthrough in Healthcare",
      "source": "TechCrunch",
      "url": "https://example.com/article",
      "published_at": "2026-02-06T14:22:00Z",
      "description": "Researchers announce...",
      "category": "technology"
    }
  ],
  "source": "newsapi",
  "timestamp": "2026-02-06T15:30:00Z"
}

Forex API Starter

GET/v1/forex

Current exchange rates from the European Central Bank. Updated daily.

Parameter	Type	Required	Description
`base`	string	optional	Base currency (default: USD)
`symbols`	string	optional	Comma-separated target currencies (e.g., EUR,GBP,JPY)

{
  "status": "success",
  "data": {
    "base": "USD",
    "date": "2026-02-06",
    "rates": {
      "EUR": 0.9234,
      "GBP": 0.7891,
      "JPY": 148.52
    }
  },
  "source": "frankfurter",
  "timestamp": "2026-02-06T15:30:00Z"
}

GET/v1/forex/history

Historical exchange rate for a specific date.

Parameter	Type	Required	Description
`date`	string	required	Date in YYYY-MM-DD format
`base`	string	optional	Base currency (default: USD)
`symbols`	string	optional	Comma-separated target currencies

Timezone API Starter

GET/v1/timezone

Current time and date info for any timezone.

Parameter	Type	Required	Description
`location`	string	required	IANA timezone (e.g., America/New_York, Europe/London)

{
  "status": "success",
  "data": {
    "timezone": "America/New_York",
    "datetime": "2026-02-06T10:30:00.123456-05:00",
    "utc_offset": "-05:00",
    "abbreviation": "EST",
    "day_of_week": 5,
    "week_number": 6,
    "dst": false
  },
  "source": "worldtimeapi",
  "timestamp": "2026-02-06T15:30:00Z"
}

GET/v1/timezone/list

List all available IANA timezone identifiers.

Air Quality API Starter

GET/v1/air-quality

US AQI index, PM2.5, ozone, and other pollutant readings.

Parameter	Type	Required	Description
`location`	string	required*	City name
`lat`	number	required*	Latitude. Use with lon instead of location.
`lon`	number	required*	Longitude

{
  "status": "success",
  "data": {
    "aqi": 42,
    "category": "good",
    "pm2_5": 8.3,
    "pm10": 15.1,
    "ozone": 68.2,
    "nitrogen_dioxide": 12.4,
    "carbon_monoxide": 201.5,
    "location": "Tokyo, Japan"
  },
  "source": "open-meteo",
  "timestamp": "2026-02-06T15:30:00Z"
}

AQI categories: good (0-50), moderate (51-100), unhealthy_sensitive (101-150), unhealthy (151-200), very_unhealthy (201-300), hazardous (301+)

Geocode API Starter

GET/v1/geocode

Convert city names to coordinates, country codes, population, and timezone.

Parameter	Type	Required	Description
`query`	string	required	City or place name
`limit`	integer	optional	Number of results (1-10, default: 5)

{
  "status": "success",
  "data": [
    {
      "name": "London",
      "country": "United Kingdom",
      "country_code": "GB",
      "admin1": "England",
      "latitude": 51.50853,
      "longitude": -0.12574,
      "elevation": 25,
      "population": 7556900,
      "timezone": "Europe/London"
    }
  ],
  "count": 1,
  "source": "open-meteo",
  "timestamp": "2026-02-06T15:30:00Z"
}

IP Lookup API Starter

GET/v1/ip-lookup

Geolocation, ISP info, and timezone from any IP address. Omit the ip parameter to look up the requesting IP.

Parameter	Type	Required	Description
`ip`	string	optional	IP address to look up (default: your IP)

{
  "status": "success",
  "data": {
    "ip": "8.8.8.8",
    "country": "United States",
    "country_code": "US",
    "region": "Virginia",
    "city": "Ashburn",
    "zip": "20149",
    "latitude": 39.03,
    "longitude": -77.5,
    "timezone": "America/New_York",
    "isp": "Google LLC",
    "org": "Google Public DNS"
  },
  "source": "ipwho",
  "timestamp": "2026-02-06T15:30:00Z"
}

Holidays API Starter

GET/v1/holidays

Public holidays for 100+ countries.

Parameter	Type	Required	Description
`country`	string	optional	ISO 3166-1 country code (default: US)
`year`	integer	optional	Year (default: current year)

{
  "status": "success",
  "data": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "name_en": "New Year's Day",
      "country_code": "US",
      "fixed": true,
      "global": true,
      "type": "public"
    }
  ],
  "count": 11,
  "source": "nager-date",
  "timestamp": "2026-02-06T15:30:00Z"
}

Endpoint Discovery Free

GET/v1/endpoints

See all available endpoints and which ones your plan can access.

{
  "status": "success",
  "plan": "free",
  "total_endpoints": 18,
  "accessible": 5,
  "endpoints": {
    "weather": { "path": "/v1/weather", "tier": "free", "accessible": true },
    "forex": { "path": "/v1/forex", "tier": "starter", "accessible": false },
    ...
  }
}

Batch Requests Free

POST/v1/batch

Send up to 10 requests in a single call. Each item in the array specifies an endpoint and its parameters.

curl -X POST -H "x-api-key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "endpoint": "weather", "params": { "location": "miami" } },
      { "endpoint": "crypto", "params": { "symbol": "BTC" } },
      { "endpoint": "news", "params": { "category": "technology" } }
    ]
  }' \
  "https://sprime.us/v1/batch"

Each batch item counts as one request toward your daily limit. The batch will be rejected if it would exceed your remaining quota.

Webhooks Pro

POST/v1/webhooks/register

Register a webhook to receive push notifications when conditions are met. Supports crypto price thresholds, weather alerts, and news keyword matching. Webhooks are checked when data is fetched (event-driven, not background polling) and capped at 1 delivery per hour per webhook.

Webhook URLs must use HTTPS and pass DNS validation. Deliveries include an HMAC-SHA256 signature for verification.

GET/v1/webhooks/list

List all active webhooks for your API key.

DELETE/v1/webhooks/:id

Deactivate a webhook by its ID.

Rate Limits & Caching

Daily request limits based on your plan:

Plan	Requests/Day	Endpoints	Weather TTL
Free	500	3 core	10 min
Starter	5,000	15+	5 min
Pro	20,000	All + Webhooks	2 min

The Weather TTL above is plan-specific. Other endpoints use fixed TTLs regardless of plan: crypto caches for 2 minutes, news for 15 minutes, timezone for 1 minute, air quality for 10 minutes, and static data (forex, holidays, geocoding, IP) for 24 hours. All requests count toward your daily limit.

Data endpoint responses include these headers:

Header	Description
`X-Cache-Hit`	true/false
`X-Cache-Age`	Seconds since data was cached
`X-Cache-TTL`	Cache lifetime in seconds
`X-Next-Update`	ISO timestamp when fresh data will be fetched
`X-Rate-Limit-Remaining`	Requests left today

Error Handling

All errors return a consistent format:

{
  "error": "Invalid API key"
}

Code	Meaning
400	Bad request (missing or invalid parameters)
401	Unauthorized (invalid or missing API key)
403	Endpoint restricted (upgrade your plan)
429	Rate limit exceeded
500	Server error

API Documentation

Endpoints