Universal Tutorial Logo Universal TutorialUniversal Tutorial Logo Universal Tutorial

Free REST API for countries, states and cities

Follow the below steps from which you can access the free APIs for the country, state, and city information



Generate token







Steps to access the APIs

Step 1 GET https://www.universal-tutorial.com/api/getaccesstoken

Before consuming any of the APIs, Generate the Authorization token using the above mentioned URL along with your email and api_token, In the response you will be seeing the auth_token which needs to passed in any API using the Bearer Authentication as shown below

var req = unirest("GET", "https://www.universal-tutorial.com/api/getaccesstoken");

  req.headers({
    "Accept": "application/json",
    "api-token": "AuXnFjES43NqbdODZoc1anLtpO9op_9HsA7hqU56HJoxlbbNrMsUAzmsp6cqoZ0HhWQ",
    "user-email": "abc@gmail.com"
  });
  
Response

{
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJfZW1haWwiOiJtdmdhZGFnaUBnbWFpbC5jb20ifSwiZXhwIjoxNTY2MjM0ODU0fQ.nMWPN38zptwwDKAo11bFyjhCRuzNhZc6NqqCaYJVxP0"
}

Step 2 GET https://www.universal-tutorial.com/api/countries

Using the api_token and the token you have got in the above response you can make any of the REST APIs

var req = unirest("GET", "https://www.universal-tutorial.com/api/countries/");

  req.headers({
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJfZW1haWwiOiJtdmdhZGFnaUBnbWFpbC5jb20ifSwiZXhwIjoxNTY2MjM0ODU0fQ.nMWPN38zptwwDKAo11bFyjhCRuzNhZc6NqqCaYJVxP0",
    "Accept": "application/json"
  });
Response

[
    {
      "country_name": "Afghanistan",
      "country_short_name": "AF",
      "country_phone_code": 93
    },
    {
      "country_name": "Albania",
      "country_short_name": "AL",
      "country_phone_code": 355
    },
    {
      "country_name": "Zimbabwe",
      "country_short_name": "ZW",
      "country_phone_code": 263
    }
]




Step 3 GET https://www.universal-tutorial.com/api/states/United States

By using the country name as shown the URL will give you all the states belonging to the countries

Response
[
    {
        "state_name": "Alabama"
    },
    {
        "state_name": "Alaska"
    },
    {
        "state_name": "Arizona"
    },
    {
        "state_name": "Arkansas"
    },
    {
        "state_name": "Byram"
    },
    {
      "state_name": "Wyoming"
    }
]




Step 4 GET https://www.universal-tutorial.com/api/cities/Alaska

By using the state name will give you all the cities belonging to the states

[
    {
        "city_name": "Anchorage"
    },
    {
        "city_name": "Barrow"
    },
    {
        "city_name": "Bethel"
    },
    {
      "city_name": "Wasilla"
    }
]

Share this page


Comments

User
Universal Tutorial

Some updates have been done to increase the API performance today !!

Jan 18, 2020, 3:55:34 PM

User
Delprane Dela

Hi. First of all, thank you soo much for this API resource. it has been really helpful to some of us. But I would like to make a request. As I am from Ghana, I tried to select Ghana which works fine. But when I select or hit the cities endpoint with the Greater Accra Region as the parameter, I get an empty array, can this be fixed, please?

Jan 24, 2020, 1:54:12 PM

User
Universal Tutorial

@Delprane Dela, It's our pleasure to help you, we have done the update based on your request, kindly revert us back with your comments here or you can reach us at ask@universal-tutorial.com for any further modifications or new requests !!

Jan 24, 2020, 4:33:18 PM

User
Hammad Rasheed

It stops responding after 24 hour of auth token generation. May I need to create new auth token every day?

Feb 16, 2020, 6:33:45 PM

User
Universal Tutorial

@Hammad, Due to security reason we expiry auth_token every 24 hrs hence users are requested to do https://www.universal-tutorial.com/api/getaccesstoken to get the new token and also we are improving the errors returned during any action in upcoming weeks.

Feb 17, 2020, 11:32:23 AM

User
Universal Tutorial

We have updated our APIs to show very useful message during the auth_token expiration, so API response status would be 500 and the api response would be as below during such condition { "error": { "name": "TokenExpiredError", "message": "jwt expired", "expiredAt": "2020-02-18T17:55:22.000Z" } } This helps every one to read the error message easily and if it's expired token ,you can generate the new one

Feb 18, 2020, 5:59:13 PM

User
Shubham Naik

i am getting 504 GateWay Timeout when a sent a request . Why is it So ?

Feb 19, 2020, 4:49:57 PM

User
Universal Tutorial

@Shubham, Can you please share us the API endpoint which you are trying along with the headers in an email to ask@universal-tutorial.com, So that we can help quickly.

Feb 19, 2020, 5:37:30 PM

User
Shubham Naik

I am sending 'get' request using Postman . Request url is : https://www.universal-tutorial.com/api/countries/ and the body in json is : { "Authorization": "nLsYM6PoE9D9ReXB_IvI-i2X-70ZauAITWgW4yiRAsEdcVsORc2awdoA5hPLroae94c eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJfZW1haWwiOiJtdmdhZGFnaUBnbWFpbC5jb20ifSwiZXhwIjoxNTY2MjM0ODU0fQ.nMWPN38zptwwDKAo11bFyjhCRuzNhZc6NqqCaYJVxP0", "Accept": "application/json" }

Feb 20, 2020, 2:36:01 AM

User
Sangam Basnet

Everything is fine with the API, but it's strange that the retrieved states are not actually in real for those countries. One example is for Australia. How many states in Australia in google gives 6 in number. But here in API response gives more than that. I assume rest of the other than 6 are suburbs name. Which is not meaningful. Thank you.

Feb 20, 2020, 2:54:33 AM

User
Sangam Basnet

HI

Feb 20, 2020, 2:54:56 AM

User
Universal Tutorial

@Sangam, Thanks for your valuable feedback and we will analyse and update the information accordingly.

Feb 20, 2020, 4:06:51 PM