Countries API

General Information

The Countries API was built by The Easy API and maintains the data locally. The data recently went through an overhaul using various providers to include better coverages across the globe. This was one API that we coordinated with a great partner of ours who requested various changes.

Provider Source

GeoNames provides initial data

Methods

Method - getcountries

This should be the first method used to return all countries and their abbreviations. Particular importance is the returned element of abbr which is used in subsequent requests.

Request

https://json.theeasyapi.com/{api_key}/?service=countries&method=getcountries

Response

{
  "countries": {
    "country": [
      {
        "abbr": "AF",
        "name": "Afghanistan"
      },
      {
        "abbr": "AX",
        "name": "Åland Islands"
      },
      {
        "abbr": "AL",
        "name": "Albania"
      },
      {
        "abbr": "DZ",
        "name": "Algeria"
      },
      {...},
      {
        "abbr": "YE",
        "name": "Yemen"
      },
      {
        "abbr": "ZM",
        "name": "Zambia"
      },
      {
        "abbr": "ZW",
        "name": "Zimbabwe"
      }
    ]
  }
}

Method - getregions

This method will return the states/provinces/regions within a selected country which uses the abbr field from getcountries. Particular importance for this returned data includes the stateid which can be used in the getcities method call.

Required Parameters

Request

https://json.theeasyapi.com/{api_key}/?service=countries&method=getregions&country=ZM

Response

{
  "countries": {
    "region": [
      {
        "stateid": "02",
        "name": "Central Province"
      },
      {
        "stateid": "08",
        "name": "Copperbelt Province"
      },
      {
        "stateid": "03",
        "name": "Eastern Province"
      },
      {
        "stateid": "04",
        "name": "Luapula Province"
      },
      {
        "stateid": "09",
        "name": "Lusaka Province"
      },
      {
        "stateid": "10",
        "name": "Muchinga Province"
      },
      {
        "stateid": "06",
        "name": "North-Western Province"
      },
      {
        "stateid": "05",
        "name": "Northern Province"
      },
      {
        "stateid": "07",
        "name": "Southern Province"
      },
      {
        "stateid": "01",
        "name": "Western Province"
      }
    ]
  }
}

Method - getcities

This method requires the stateid along with the abbr country and returns all cities which have a population. The distinction here is that it will include state/region capitals along with all cities which have a population greater than 0. This provides a unique blend of significant cities without displaying all uninhabited ones as well.

Required Parameters

Request

https://json.theeasyapi.com/{api_key}/?service=countries&method=getcities&country=ZM&stateid=04

Response

{
  "countries": {
    "cities": {
      "city": [
        {
          "name": "Mansa",
          "latitude": "-11.19976",
          "longitude": "28.89431",
          "timezone": "Africa/Lusaka",
          "type": "Capital",
          "population": "42277"
        },
        {
          "name": "Kawambwa",
          "latitude": "-9.7915",
          "longitude": "29.07913",
          "timezone": "Africa/Lusaka",
          "type": "City",
          "population": "20589"
        },
        {
          "name": "Mwense",
          "latitude": "-10.38447",
          "longitude": "28.698",
          "timezone": "Africa/Lusaka",
          "type": "City",
          "population": "4378"
        },
        {
          "name": "Nchelenge",
          "latitude": "-9.34506",
          "longitude": "28.73396",
          "timezone": "Africa/Lusaka",
          "type": "City",
          "population": "23693"
        },
        {
          "name": "Samfya",
          "latitude": "-11.36491",
          "longitude": "29.55652",
          "timezone": "Africa/Lusaka",
          "type": "City",
          "population": "20470"
        }
      ]
    }
  }
}

Possible Errors

Request

https://json.theeasyapi.com/{api_key}/?service=countries&method=getregions&country=AA

Response

{
  "countries": {
    "country_regions": {
      "errors": "1",
      "errorcode": "region_1000",
      "reason": "You have provided a country which either has no regions/states or the country code is wrong."
    }
  }
}

Request

https://json.theeasyapi.com/{api_key}/?service=countries&method=getcities&country=ZM&stateid=12

Response

{
  "countries": {
    "country_regions": {
      "errors": "1",
      "errorcode": "city_1001",
      "reason": "You have provided a country / region which either has no cities or the stateId is wrong."
    }
  }
}