Flags API

The Flags API provides access to country and territory information, including flag images, capitals, regions, populations, languages, currencies and the Flag of the Day (OTD).

Base Endpoint
/api/flags/[action]/[object]
Part Description
action The operation to perform.
object Optional value used by the selected action.
Available Endpoints
Endpoint Description
/api/flags List countries and territories.
/api/flags/random Return a random country.
/api/flags/otd Return the current Flag of the Day.
/api/flags/id/{id} Lookup by internal ID.
/api/flags/code/{code} Lookup by ISO code.
/api/flags/name/{name} Lookup by country name.
/api/flags/search/{query} Search by name, capital or ISO code.
/api/flags/continent/{continent} Countries in a continent.
/api/flags/region/{region} Countries in a region.
/api/flags/subregion/{subregion} Countries in a subregion.
/api/flags/continents List continents with counts.
/api/flags/regions List regions with counts.
/api/flags/count Flag database statistics.
Query Parameters
Parameter Example Description
limit 25 Maximum number of results returned.
continent Europe Filter countries by continent.
region Caribbean Filter countries by region.
subregion Lesser Antilles Filter countries by subregion.
Examples
GET /api/flags
GET /api/flags?limit=50
GET /api/flags/random
GET /api/flags/random?continent=Europe
GET /api/flags/otd
GET /api/flags/id/5
GET /api/flags/code/GB
GET /api/flags/code/US
GET /api/flags/name/France
GET /api/flags/search/ang
GET /api/flags/continent/Europe
GET /api/flags/region/Caribbean
GET /api/flags/subregion/Lesser Antilles
GET /api/flags/continents
GET /api/flags/regions
GET /api/flags/count
Flag Of The Day (OTD)
OTD Generation Rules
  • If a country already exists with today's otd value, it is returned.
  • If no country exists for today, a random country is selected.
  • The selected country cannot be one of the last 30 countries used as OTD.
  • The country's otd field is set to the current date.
  • The selected country is returned as the new Flag of the Day.
Flag Images

Every country response includes image URLs generated from the ISO country code. 

"images": {
    "100": "https://jarvisbot.uk/media/flags/png100px/gb.png",
    "250": "https://jarvisbot.uk/media/flags/png250px/gb.png",
    "1000": "https://jarvisbot.uk/media/flags/png1000px/gb.png",
    "svg": "https://jarvisbot.uk/media/flags/svg/gb.svg"
}
Example Country Response
{
    "id": 5,
    "code": "AI",
    "name": "Anguilla",
    "capital": "The Valley",
    "continent": "North America",
    "region": "Caribbean",
    "subregion": "Lesser Antilles",
    "population": "15000",
    "area_km2": "91",
    "currency": "East Caribbean Dollar (XCD)",
    "languages": [
        "English"
    ],
    "calling_code": "+1-264",
    "timezones": [
        "UTC−4"
    ],
    "independent": "no",
    "government": "British Overseas Territory",
    "major_cities": [
        "The Valley",
        "Blowing Point",
        "Sandy Ground"
    ],
    "description": "Anguilla is a small British territory known for its pristine beaches, turquoise waters, and luxury tourism.",
    "otd": null,
    "images": {
        "100": "https://jarvisbot.uk/media/flags/png100px/ai.png",
        "250": "https://jarvisbot.uk/media/flags/png250px/ai.png",
        "1000": "https://jarvisbot.uk/media/flags/png1000px/ai.png",
        "svg": "https://jarvisbot.uk/media/flags/svg/ai.svg"
    }
}
Example Continents Response
[
    {
        "continent": "Africa",
        "count": 54
    },
    {
        "continent": "Europe",
        "count": 44
    },
    {
        "continent": "North America",
        "count": 41
    }
]
Example Statistics Response
{
    "total": 249,
    "continents": 7,
    "regions": 23,
    "otd_used": 156
}

Authentication & Rate Limits

All Jarvis APIs require a valid API token. Tokens are issued through the Jarvis Developer Portal and are associated with an account plan which determines access levels and request limits.

Authentication

Every request must include a valid API token. Requests made without a token or with an invalid token will be rejected.

Authorization Header (Recommended)
Authorization: YOUR_API_TOKEN
X-API-Token Header
X-API-Token: YOUR_API_TOKEN
Query String
GET /api/flags/random?token=YOUR_API_TOKEN
For security reasons, the Authorization header method is strongly recommended. Avoid exposing API tokens in URLs where possible.
Example Requests
cURL
curl \
-H "Authorization: YOUR_API_TOKEN" \
https://jarvisbot.uk/api/flags/random
JavaScript (Fetch)
fetch("https://jarvisbot.uk/api/jokes/random", {
    headers: {
        "Authorization": "YOUR_API_TOKEN"
    }
})
.then(r => r.json())
.then(console.log);
PHP
$response = file_get_contents(
    "https://jarvisbot.uk/api/questions/random",
    false,
    stream_context_create([
        'http' => [
            'header' => [
                'Authorization: YOUR_API_TOKEN'
            ]
        ]
    ])
);

$data = json_decode($response, true);
Account Plans
Plan Daily Requests API Access
Free 100 Requests Basic APIs
Premium 10,000 Requests All APIs
Enterprise Unlimited All APIs + Priority Support
Rate Limiting

API usage is automatically monitored based on your account type. Once your limit is reached, requests will be temporarily blocked until your allowance resets.

Plan Limit Window
Free 100 Requests 24 Hours
Premium 10,000 Requests 24 Hours
Enterprise Unlimited No Restriction
Authentication Error Response
{
    "success": false,
    "error": "invalidToken",
    "msg": "API token required"
}
Invalid Token Response
{
    "success": false,
    "error": "invalidToken",
    "msg": "Invalid API token"
}
Rate Limit Response
{
    "success": false,
    "error": "rateLimit",
    "msg": "API limit exceeded",
    "plan": "free",
    "limit": 100
}
Best Practices
  • Store API tokens securely and never expose them publicly.
  • Use the Authorization header whenever possible.
  • Cache responses where appropriate to reduce API calls.
  • Monitor your daily usage to avoid rate limiting.
  • Upgrade your account if your application requires higher throughput.
Supported APIs
  • Flags API
  • Dictionary API
  • Questions API
  • Riddles API
  • Jokes API
  • Pickup Lines API
  • Truth Or Dare API
  • Harry Potter Spells API
  • Future Jarvis APIs
Need additional capacity or custom limits? Contact the Jarvis team to discuss Premium and Enterprise API access.