Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AndresLopezCorrales/Countries-WebPage/llms.txt

Use this file to discover all available pages before exploring further.

Country-Click uses the public REST Countries API v3.1 (no authentication required) to fetch live country data on every search or map click. The API is called server-side from PHP using file_get_contents(), which means the browser never communicates directly with restcountries.com — all requests originate from the PHP server. No API key or registration is needed.

​
Endpoint

The application uses a single endpoint throughout, accessed via an HTTP GET request issued by file_get_contents().
PropertyValue
MethodGET (via file_get_contents)
URL patternhttps://restcountries.com/v3.1/name/{name}
AuthenticationNone required
Example URLs: 
https://restcountries.com/v3.1/name/Germany
https://restcountries.com/v3.1/name/Federal%20Republic%20of%20Germany
https://restcountries.com/v3.1/name/Spain
The {name} segment accepts either a country’s common English name or its official name. Spaces in multi-word names are percent-encoded as %20 before the URL is constructed.

​
Request construction

Before making the request, getSearchBarInfo() replaces any spaces in the country name with %20 using str_replace(). It then appends the name to the base URL and creates a stream context with ignore_errors set to true. This setting is critical: it ensures that non-2xx HTTP responses (such as a 404 from the API) are returned as the response body rather than causing file_get_contents() to return false and emit a PHP warning. The file_get_contents() call itself is wrapped in its own inner try/catch so that a network-level exception can be caught and surfaced as a user-friendly message.
ApiConsumer.php
$nameCountry = str_replace(" ", "%20", $nameCountry);
$url = "https://restcountries.com/v3.1/name/$nameCountry";

ini_set('http_errors', 0);

$context = stream_context_create([
    'http' => [
        'ignore_errors' => true
    ]
]);

try {
    $response = file_get_contents($url, false, $context);
} catch (Exception $e) {
    echo "<p>Doesn't exist. Try with the official name or the english name.</p>";
}

​
Response structure

The REST Countries API returns a JSON array. Country-Click always reads from the first element ($data[0]). The following fields are used by GetAttributesController:
​
[0].name.common
string
The country’s common English name, for example "Germany". Displayed as the primary heading in the info panel.
​
[0].name.official
string
The country’s full official name, for example "Federal Republic of Germany". Displayed as a subtitle beneath the common name.
​
[0].flags.png
string
A URL pointing to a PNG image of the country’s flag, for example "https://flagcdn.com/w320/de.png". Used as the src of an <img> tag in the info panel.
​
[0].capital[0]
string
The primary capital city of the country, for example "Berlin". Only the first element of the capital array is read.
​
[0].population
number
The total population count as an integer, for example 83240525. Displayed directly in the info panel without formatting.
​
[0].languages
object
A map of ISO 639-3 language codes to language name strings, for example {"deu": "German"}. GetAttributesController::getLanguage() iterates over this object and collects the values; ApiConsumer then joins them into a comma-separated string with implode().
​
[0].timezones[0]
string
The primary timezone as a UTC offset string, for example "UTC+01:00". Only the first element of the timezones array is read.
​
[0].region
string
The continent or world region the country belongs to. Possible values used by Country-Click: "Africa", "Americas", "Asia", "Europe", "Oceania". This value also determines which regional map image is shown in the info panel.
​
status
number
Present only in error responses. The HTTP status code returned when the API cannot find a matching country, for example 404. Country-Click checks $data["status"] (top-level key, not nested under $data[0]) to detect a failed lookup.
​
message
string
Present only in error responses. A human-readable error string such as "Page Not Found". Country-Click checks $data["message"] (top-level key) as a secondary guard against unrecognised country names.

​
Error handling

Country-Click performs three distinct error checks after the API call returns. First it verifies that file_get_contents() did not fail outright. Then it decodes the JSON and inspects it for the API’s own error fields before attempting to extract country data. Note that the error status fields (status and message) are top-level keys on the decoded array, not nested under $data[0].
ApiConsumer.php
if ($response === false) {
    throw new Exception('Error al obtener la respuesta de la API');
}

$data = json_decode($response, true);

if (isset($data["status"]) && $data["status"] === 404
    || isset($data["message"]) && $data["message"] === "Page Not Found") {
    echo "<p>Doesn't exist. Try with the official name or the english name.</p>";
}
If the $response === false check is triggered, the exception is caught by the surrounding try/catch block in getSearchBarInfo() and a generic error string is returned. If the API returns a 404 JSON payload, the user is shown a message asking them to try the country’s official or English name.
The API returns an array of matching countries. Country-Click always reads $data[0] (the first match). For most searches this is the correct country, but very generic searches (e.g., “island”) might return the first alphabetical match rather than the intended result. Using the country’s full common English name or its official name gives the most reliable results.

​
Sample API response

The following is an abbreviated example of what the REST Countries API returns for a query to https://restcountries.com/v3.1/name/Germany:
Example: Germany
[
  {
    "name": {
      "common": "Germany",
      "official": "Federal Republic of Germany"
    },
    "capital": ["Berlin"],
    "population": 83240525,
    "languages": { "deu": "German" },
    "timezones": ["UTC+01:00"],
    "region": "Europe",
    "flags": {
      "png": "https://flagcdn.com/w320/de.png"
    }
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us