RESTful web-service to get and search States and territories of a Country

130013

Mar 20, 2016

Here is a RESTful web service to get and search states and territories of a country. This web service can be used for testing, learning or can be consumed for any web application.

1. REST web-service to get a list of all States and territories of a country

Each country has 3 character ISO assigned code assigned to it. Below service can be used to get all states of a country. Use this web-service to know the iso codes of countries.

http://services.groupkt.com/state/get/{countryCode}/all

example http://services.groupkt.com/state/get/IND/all

This rest web service will return a list countries in JSON format, each country object has


{
      "country" : "IND",
      "name" : "Andhra Pradesh",
      "abbr" : "AP",
      "area" : "160205KMS",
      "largest_city" : "Visakhapatnam",
      "capital" : "Hyderabad"
    }

2. REST web-service to search state of a country

To search the state of a Country by its code use this service, it will return a state matching the requested code.

The url for this web service is /get/{countryCode}/{stateCode} for example


http://services.groupkt.com/state/get/IND/UP

This rest web service will search and return the matching state the search result will be similar to


{
  "RestResponse" : {
    "messages" : [ "State found matching code [UP]." ],
    "result" : {
      "country" : "IND",
      "name" : "Uttar Pradesh",
      "abbr" : "UP",
      "area" : "243286KMS",
      "capital" : "Lucknow"
    }
  }
}

and if nothing matching found then


{
  "RestResponse" : {
    "messages" : [ "No matching state found for requested code [IND->UF]." ]
  }
}

3. REST web-service to search state by any free form text

This will search the input string in state name or code

The url for this web service is http://services.groupkt.com/state/search/{countryCode}?text={text to search} for example


http://services.groupkt.com/state/search/IND?text=pradesh

This rest web service will search and return the matching states of a country


{
  "RestResponse" : {
    "messages" : [ "Total [5] records found." ],
    "result" : [ {
      "country" : "IND",
      "name" : "Andhra Pradesh",
      "abbr" : "AP",
      "area" : "160205KMS",
      "largest_city" : "Visakhapatnam",
      "capital" : "Hyderabad"
    }, {
      "country" : "IND",
      "name" : "Arunachal Pradesh",
      "abbr" : "AR",
      "area" : "83743KMS",
      "capital" : "Itanagar"
    }, {
      "country" : "IND",
      "name" : "Himachal Pradesh",
      "abbr" : "HP",
      "area" : "55673KMS",
      "capital" : "Shimla"
    }, {
      "country" : "IND",
      "name" : "Madhya Pradesh",
      "abbr" : "MP",
      "area" : "308252KMS",
      "largest_city" : "Indore",
      "capital" : "Bhopal"
    }, {
      "country" : "IND",
      "name" : "Uttar Pradesh",
      "abbr" : "UP",
      "area" : "243286KMS",
      "capital" : "Lucknow"
    } ]
  }
}

and if nothing matching found then


{
  "RestResponse" : {
    "messages" : [ "No matching state found for requested code [IND->upp]." ],
    "result" : [ ]
  }
}

To test above services just click the example link or copy/paste the example link in browser's address bar and you will get the JSON Rest response.
If you are using Java,then you can integrate this web service with your code either by using Spring's org.springframework.web.client.RestTemplate or Apache's HTTPClient

Currently states list is available for India only

* Web Service to get location by IP
For other available REST web services visit http://www.groupkt.com/post/f2129b88/free-restful-web-services.htm

comments powered by Disqus