Countries

Overview

By default, our API endpoints return the complete data object for a country, ensuring you have immediate access to every available field. However, for production applications, we strongly recommend fetching only the specific fields you need.

While convenient, retrieving the full object when you only require specific data points (e.g., just currencySymbol and tld) creates unnecessary overhead.

Why granular requests matter:

• Network Latency: Smaller payloads travel faster, especially on mobile networks.
• Bandwidth Usage: Reducing the response body size lowers data consumption for both your server and your user.
• Serialization Costs: Massive JSON objects take longer for the API to generate and longer for your client to parse.

GET /v1/geo/countries/all

Request

Query Parameters: The fields parameter is optional. It accepts a comma-separated list of valid property names to include in the response object.

curl -X GET "https://api.geoapi.net/v1/geo/countries/all?fields=iso2,population,currencyCode,isEu" \
     -H "X-API-HOST: your_api_host" \
     -H "X-API-KEY: your_api_key"

Response

The API returns a lightweight array containing only the requested data points:

[
  {
    "iso2": "AF",
    "population": 40218234,
    "currencyCode": "AFN",
    "isEu": false
  },
  {
    "iso2": "AL",
    "population": 2837743,
    "currencyCode": "ALL",
    "isEu": false
  }
  ...
]

GET /v1/geo/countries/{countryCode}

Request

Path Parameters: The countryCode is a mandatory parameter. It accepts either the ISO 3166-1 alpha-2 (2-letter) or alpha-3 (3-letter) code to identify the resource.

Query Parameters: The fields parameter is optional. It accepts a comma-separated list of valid property names to include in the response object.

curl -X GET "https://api.geoapi.net/v1/geo/countries/AL?fields=countryName,population,currencyCode,isEu" \
     -H "X-API-HOST: your_api_host" \
     -H "X-API-KEY: your_api_key"

Response

The API will return a single JSON object containing strictly the keys requested in your query.

{
  "countryName": "Albania",
  "population": 2837743,
  "currencyCode": "ALL",
  "isEu": false
}

Error occurs if you pass non existing country countryCode, or not 2-3 letters long.

{
  "status": 404,
  "message": "Not Found"
}

Query Parameters