REST-Jdbc — REST Countries

REST Countries provides country data (names, codes, region, population, and more). The current v5 API is read-only and requires a free API key (sign up on the website).

Quick start with the JDBC client

java -jar /path/to/restjdbc.jar restcountries.sql

The file restcountries.sql contains the connection and sample queries. Steps:

1. Obtain the driver JAR (absolute path to restjdbc.jar)
2. Create a free API key at restcountries.com/sign-up
3. Replace token=XXXX in restcountries.sql with your key
4. Run the command in the folder containing restcountries.sql and restcountries-spec.json

connect 'jdbc:rest:https://api.restcountries.com|spec=restcountries-spec.json,auth=bearer,token=Your_Key'

1. JDBC URL

jdbc:rest:https://api.restcountries.com

The API base URL is set in the JDBC URL.

Part	Value
Driver prefix	jdbc:rest:
API base URL	https://api.restcountries.com
SQL schema	public (default)

Connection example (Java):

Properties props = new Properties();
props.setProperty("spec", "/path/to/restcountries-spec.json");
props.setProperty("auth", "bearer");
props.setProperty("token", System.getenv("RESTCOUNTRIES_API_KEY"));

Connection conn = DriverManager.getConnection(
    "jdbc:rest:https://api.restcountries.com", props);

2. Connection properties

Property	Value	Required
spec	Path to spec	Yes
auth	bearer	Yes
token	REST Countries API key	Yes

Spec path: absolute path to your local copy of the spec file.

Spec file: restcountries-spec.json

3. Spec file

File: restcountries-spec.json

Excerpt:

{
  "entities": [
    {
      "name": "countries",
      "path": "/countries/v5",
      "dataPath": "/data/objects",
      "pagination": {
        "type": "offset",
        "limitParam": "limit",
        "offsetParam": "offset",
        "defaultLimit": 25
      },
      "write": false,
      "columns": [
        { "name": "alpha_2", "type": "VARCHAR", "primaryKey": true, "jsonPath": "/codes/alpha_2" },
        { "name": "name", "type": "VARCHAR", "jsonPath": "/names/common" },
        { "name": "region", "type": "VARCHAR" },
        { "name": "population", "type": "BIGINT" }
      ]
    }
  ]
}

Table countries

SQL table	REST path	Pagination
countries	/countries/v5	offset with limit / offset (max 25 per page on free tier)

Rows are under data.objects (dataPath). Nested fields use jsonPath.

"write": false — SELECT only.

4. Authentication

REST Countries v5 requires an API key as a bearer token:

props.setProperty("auth", "bearer");
props.setProperty("token", "rc_live_…");

The driver sends: Authorization: Bearer rc_live_…

Older unauthenticated versions (v1–v3) are shut down — only v5 is available.

5. SQL examples

SELECT

SELECT alpha_2, name, region, population FROM countries;

SELECT alpha_2, name, region FROM countries FILTER region=Europe;

SELECT alpha_2, name FROM countries FILTER q=Germany;

SQL	HTTP
SELECT … FROM countries	GET …/countries/v5?limit=25&offset=0, then offset=25, …
SELECT … FILTER region=Europe	GET …/countries/v5?region=Europe&limit=25&offset=0, …
SELECT … FILTER q=Germany	GET …/countries/v5?q=Germany&limit=25&offset=0, …

FILTER forwards query parameters to the API. With offset pagination the driver fetches all pages automatically.

INSERT, UPDATE, DELETE

Not supported ("write": false).

6. System tables

SELECT table_name FROM system.table_list;

SELECT column_name, type_name FROM system.column_list WHERE table_name = 'countries';

7. Notes

• Free tier: Limited requests per month — see REST Countries pricing.
• Demo key: rc_live_demo returns sample data for testing response shape only.
• More fields: 80+ fields per country — add columns with jsonPath in the spec (e.g. /capitals/0 for capital).