The Countries plugin lets you retrieve global country data directly inside your Bubble app, with flexible search options. You can pull a full list of all countries or look them up individually by name, capital city, ISO alpha code, or spoken language — making it a great fit for travel apps, location-based services, internationalization, and any workflow that needs reliable country-level data (names, flags, currencies, languages, regions, borders, population, and more).
The plugin connects to version 5 of the Countries API. This version requires an API key.
An optional Countries cache element is also included. It caches the result of "List All Countries" in the visitor's browser, so your app doesn't need to re-fetch all ~250 countries on every page load.
Prerequisites
You must have an API key to use this plugin with the v5 Countries API. Create your account and generate a key on the https://restcountries.com/, then add it in the plugin's settings (Bearer token / Authorization header) before making any API calls.
Once your key is added, install the plugin, drag the relevant API call into a workflow (or a Repeating Group's data source), and start using it.
How to setup
Get your API key for the v5 Countries API and add it in the plugin's settings (under the plugin's API connection settings, as a Bearer token / Authorization header).
Install the plugin into your Bubble app from the Plugins tab.
Choose a data source: in a Repeating Group, set its type of content to one of the plugin's API call data types (e.g. "Search Countries by Name") and its data source to the corresponding API call.
Pass any required search parameter (such as a country name, capital, alpha code, or language) either as a static value or a dynamic value from another element.
(Optional)Limit the response size by using the response_fields parameter to only return the fields you actually need (e.g. names.common,codes.alpha_2,flag.emoji) — this keeps your app fast and your data lighter.
(Optional)Add the "Countries cache" element to a reusable element or page if you plan to use "List All Countries" frequently, to avoid refetching the full country list on every load (see the Workflow example section below).
Plugin Element Properties
The plugin contains one optional visual element, Countries cache, used to cache the full country list in the visitor’s browser so it doesn’t need to be re-fetched from the API on every page load.
Countries cache
Fields:
Title
Description
Type
ℹ️ About this element
Informational label explaining what the element does and recommending you only request the fields you actually display, to keep the cached payload small
Label
Cache lifetime (in days)
How many days a cached copy stays valid before it’s considered outdated. Minimum value is 1; if left blank, 0, negative, or invalid, defaults to 30 days
Number
Countries data (List All Countries result)
Bind this to the List All Countries body data object API call’s body/data/objects field, inside a workflow step (e.g. as the result of an API call action)
Custom type (list)
Element Actions
This element exposes one action.
Update cached countries
Stores the given country list in the visitor’s browser (IndexedDB, with a localStorage fallback) along with a fresh timestamp, and publishes it to the element’s “Countries” state.
Fields:
Title
Description
Type
Countries list
The full country list to cache, passed in one go (e.g. up to ~300 records). Typically the result of the “List All Countries” API call
List
Exposed States
Name
Description
Type
Countries
The cached list of countries, available either from a fresh browser cache or after calling “Update cached countries”
List (custom type)
Element Events
Name
Description
Cache is outdated
Triggered on page load when the browser cache is missing or older than the configured “Cache lifetime (in days)”. Hook a workflow here that calls “List All Countries” and then this element’s “Update cached countries” action with the result.
Each item returned inside body data objects (for any of the calls above) shares the same general structure. The most commonly used fields are listed below; many additional nested fields are also available (translations, leaders, gini coefficients by year, membership flags, etc.) — the response only includes the fields you didn’t exclude via response_fields / response_fields_omit.
Name
Description
Type
names common
Common name of the country
Text
names official
Official name of the country
Text
codes alpha_2
2-letter ISO country code
Text
codes alpha_3
3-letter ISO country code
Text
capitals
List of capital cities (name, coordinates, attributes)
List
flag emoji
Flag as an emoji character
Text
flag url_png / url_svg
URL to the flag image (PNG / SVG)
Text
region / subregion
Geographic region / subregion
Text
continents
List of continents
List (text)
area kilometers / miles
Total area
Number
borders
List of bordering country codes
List (text)
currencies
List of currencies (code, name, symbol)
List
languages
List of languages (name, native name, ISO codes)
List
population
Total population
Number
timezones
List of timezones
List (text)
tlds
List of internet top-level domains
List (text)
links wikipedia / google_maps / official
Useful related links
Text
memberships eu / un / nato / g7 / g20 / etc.
Boolean flags for international organization membership
The REST Countries API returns a maximum of 100 records per request (limit caps at 100), while the full dataset contains around 250 countries. To cache the entire list, you need to call List All Countries 3 times with different offset values, then merge the 3 results together before saving them to the cache.
Add the Countries cache element to a reusable element that's present on page load (e.g. your header or a hidden reusable element).
Set up a workflow on "Cache is outdated" (the Countries cache element's event):
Step 1: Call List All Countries with limit = 100 and offset = 0 (records 1–100).
Step 2: Call List All Countries with limit = 100 and offset = 100 (records 101–200).
Step 3: Call List All Countries with limit = 100 and offset = 200 (records 201–~250+).
Step 4: Call the Update cached countries action, passing the merged list as the "Countries list" field:
Countries (testing) - List All Countries's body objectsmerged withCountries (testing) - List All Countries's body objectsmerged withCountries (testing) - List All Countries's body objects
(using Bubble's "merged with" operator on the body data objects result of Step 1, Step 2, and Step 3 respectively, in that order).
Changelogs
Update 23.06.26 - Version 5.0.0
Migrated to REST Countries v5 - new API host, requires a free API key.
Update 25.11.25 - Version 4.0.0
added field 'fields' in 'List All Countries' API call.
Update 08.07.25 - Version 3.17.0
Bubble Plugin Page Update (Logo).
Update 12.06.25 - Version 3.16.0
Marketing update (minor change).
Update 09.12.24 - Version 3.15.0
New API provider for List all countries call.
Update 07.11.24 - Version 3.14.0
Minor update (Marketing update).
Update 28.10.24 - Version 3.13.0
Minor update (Marketing update).
Update 11.09.24 - Version 3.12.0
Minor update (Marketing update).
Update 20.07.24 - Version 3.11.0
Minor update .
Update 06.06.24 - Version 3.10.0
Updated demo/service links.
Update 30.05.24 - Version 3.9.0
minor update.
Update 28.12.23 - Version 3.8.0
Added error message in the API calls' response.
Update 22.11.23 - Version 3.7.0
updated description.
Update 19.10.23 - Version 3.6.0
Updated description.
Update 18.09.23 - Version 3.5.0
updated description.
Update 13.09.23 - Version 3.4.0
minor updates.
Update 04.09.23 - Version 3.3.0
updated description.
Update 12.07.23 - Version 3.2.0
updated description.
Update 26.06.23 - Version 3.1.0
updated description.
Update 25.10.21 - Version 3.0.0
Moved back to the Rest Countries API on their latest version (3.1) which is free. Also added a language search..
Update 27.09.21 - Version 2.0.0
The API service has moved to a new domain. Please upgrade to this version to get the latest API. Requires API key..
Update 28.11.19 - Version 1.2.0
Added a new call to get a specific country by name.
Update 01.02.18 - Version 1.1.0
Version 2 call added to include new data like flags and CIOC code.
