REST INDIA

A RESTful API to provide information about Indian States, Union territories and Districts.

Version: 1.0.0

REST INDIA Restful API, built with Express.js and Mongodb, provides data of Indian States, Union territories and Districts with rich Endpoints to sort, search, and filter the response data.

REST INDIA also provides a limited control to select users to manage and modify stored data which assures you always get authentic and updated data.

Check the OpenAPI 3.0 specific documentation here.

Data Endpoints

Below are described the REST endpoints available that you can use to get information about Indian States, Union territories and Districts!

You can get information about Union territories under state endpoints.

All

method: GET
Response: Array of JSON Objects

All States

Get the information of all the States.

https://restindia.herokuapp.com/state/all

All Districts

Get the information of all the Districts.

https://restindia.herokuapp.com/district/all

Get the information of all the Districts of a specific State.

https://restindia.herokuapp.com/{state}/all

https://restindia.herokuapp.com/Bihar/all

https://restindia.herokuapp.com/Madhya Pradesh/all

State

method: GET
Response: Array of a JSON Object

Get information of a State by Name.

https://restindia.herokuapp.com/state/{state}

Example 1: Search a State Madhya Pradesh. Please notice the space between Madhya and Pradesh in the endpoint URL.

https://restindia.herokuapp.com/state/Madhya Pradesh

Example 2: Search a State Bihar.

https://restindia.herokuapp.com/state/Bihar

Expected Output: A JSON Array of an Object with information of Bihar.

[
  {
    "_id": "60abb8ff885176224c9df6c6",
    "iso3166code": "IN-BR",
    "code": "BR",
    "name": "Bihar",
    "capital": "Patna",
    "largestCity": "Patna",
    "districts": 38,
    "subdivisions": 101,
    "blocks": 534,
    "area": 94163,
    "literacy": 63.82,
    "sexRatio": 918,
    "population": 104099452,
    "censusYear": 2011,
    "officialWebsite": "https://state.bihar.gov.in/",
    "emblem": "https://restindia.herokuapp.com/image/emblem_Bihar.svg",
    "divisions": ["Patna", "Tirhut", "Saran", "Darbhanga", "Kosi", "Purnea", "Bhagalpur", "Munger", "Magadh"],
    "languages": ["Hindi", "Urdu", "Maithili", "Bhojpuri", "Magahi"],
    "neighbours": ["West Bengal", "Uttar Pradesh", "Nepal", "Jharkhand"]
  }
]

District

method: GET
Response: Array of a JSON Object

General Search

Get information of a District by Name.

https://restindia.herokuapp.com/district/{district}

https://restindia.herokuapp.com/district/Bhopal

State Specific Search

Get information of a District by Name. Search in a specific State.

https://restindia.herokuapp.com/{state}/{district}

Example: Search a District Sheikhpura in Bihar.

https://restindia.herokuapp.com/Bihar/Sheikhpura

Expected Output: A JSON Array of an Object with information of Sheikhpura.

[
  {
    "_id": "609e5cec0899de31888c8a84",
    "name": "Sheikhpura",
    "state": "Bihar",
    "districtCode": 26,
    "division": "Munger",
    "area": 689,
    "censusYear": 2011,
    "population": 636342,
    "literacy": 65.96,
    "sexRatio": 926,
    "officialWebsite": "https://sheikhpura.nic.in/",
    "blocks": ["Sheikhpura"],
    "subdivisions": ["Ariari", "Barbigha", "Chewara", "Ghatkusumbha", "Sheikhpura", "Shekhopur Sarai"]
  }
]

Query Parameters

method: GET

Below are some query parameters which can be used to Regex Search, Sort, Filter, and Paginate the Output Data.
You can also combine different query parameters to get elegant response.

Regex Search

Search by Name

Applicable only to ALL type Endpoints.

Search States and Districts with matching Name.

https://restindia.herokuapp.com/state/all?name={state}

https://restindia.herokuapp.com/district/all?name={district}

https://restindia.herokuapp.com/{state}/all?name={district}

Example: Search a State with Name Madhya Pradesh.

https://restindia.herokuapp.com/state/all?name=Madhya Pradesh

Expected Output: A JSON Array of Objects with information of Madhya Pradesh, Andhra Pradesh, Arunachal Pradesh, Himachal Pradesh, and Uttar Pradesh.

Search by Languages

Applicable only to ALL STATE type Endpoints.

Search States and Districts by matching Language(s).

https://restindia.herokuapp.com/state/all?languages={Language1[,Language2,...]}

Example: Search all the States containing Languages Hindi and Bhojpuri, both.

https://restindia.herokuapp.com/state/all?languages=Hindi,Bhojpuri

Search by Neighbours

Applicable only to ALL STATE type Endpoints.

Search States and Districts by matching Neighbour(s).

https://restindia.herokuapp.com/state/all?neighbours={Neighbour1[,Neighbour2,...]}

Example: Search all the States having Neighbours Bihar and West Bengal, both.

https://restindia.herokuapp.com/state/all?neighbours=Bihar,West Bengal

Search by Division

Applicable only to ALL DISTRICT type Endpoints.

Search Districts by matching Division Name.

https://restindia.herokuapp.com/district/all?division={division}

https://restindia.herokuapp.com/{state}/all?division={division}

Example: Search all the Districts which belongs to Munger division.

https://restindia.herokuapp.com/district/all?division=Munger

https://restindia.herokuapp.com/Bihar/all?division=Munger

Sort Response

Applicable only to ALL type Endpoints.

Add :asc for Ascending order sort and :desc for sorting in descending order. E.g.: population:asc

Sort the output response by field(s) Name.

https://restindia.herokuapp.com/state/all?sortby={field1:order[,field2:order,...]}

https://restindia.herokuapp.com/district/all?sortby={field1:order[,field2:order,...]}

https://restindia.herokuapp.com/{state}/all?sortby={field1:order[,field2:order,...]}

Example: Search for States, sorted by Population in Ascending Order.

https://restindia.herokuapp.com/state/all?sortby=population:asc

Expected Output: A JSON Array of Objects with information of States sorted by Population in Ascending Order.

Filter Response

Applicable to all the Endpoints.

Add prefix - for Exclusion of the fields, and optionally you can prefix + for Inclusion. Default: Inclusion.

Filter the output response by field(s) Name.

https://restindia.herokuapp.com/state/all?fields={field1[,field2,...]}

https://restindia.herokuapp.com/{state}/{district}?fields={field1[,field2,...]}

Fields must be either Inclusion or Exclusion at a time. Mixing both types will throw an Error.

Example: This is invalid Query.

https://restindia.herokuapp.com/state/bihar?fields=name,-largestCity,capital

Pagination

Applicable only to ALL type Endpoints.

Paginate and Limit the output response of All States and All Districts.

https://restindia.herokuapp.com/state/all?page={page}&limit={limit}

https://restindia.herokuapp.com/district/all?page={page}&limit={limit}

https://restindia.herokuapp.com/{state}/all?page={page}&limit={limit}

Example: Expected Output; A JSON Array of Objects with information of districts of Bihar limited to 10 districts only.

https://restindia.herokuapp.com/bihar/all?page=1&limit=10

Admin Endpoints

Approved Users can Update and Modify States and Districts Data in the Database using below Endpoints. Admin Endpoints expects Authorization Token in the Request Header.

Authentication

Authentication is the first step to access Admin Endpoints. Execute Login Endpoint to get Authorization Token.

Signup

method: POST

Signup to REST INDIA, to access the Admin Endpoints. Verification Link should be delivered to the provided email.

Make sure to have a genuine and good reason to Signup to get your account Approved by SuperAdmin.

https://restindia.herokuapp.com/admin/signup

Request Body:

{
  "name": "Vinod Sinha",
  "email": "vsinha@test.com",
  "password": "strongPass@123",
  "occupation": "Software Engineer",
  "signupReason": "Found some outdated data."
}

Response JSON:

{
  "data": "Data Object",
  "message": "Signup Successful! Verification Pending.",
  "verification": "Please verify your Email. Verification link sent to your mail: [success]",
}

Login

method: POST

Approved Users can execute this Endpoint to get Authentication Token as a JSON Response. AuthToken remains valid only for one hour.

https://restindia.herokuapp.com/admin/login

Request Body:

{
  "email": "vsinha@test.com",
  "password": "strongPass@123"
}

Response JSON:

{
  "email": "vsinha@test.com",
  "token": "**************",
  "userId": "*************"
}

Insertion

Add new Data of State and District to the Database.

Add State

method: POST

Add a new State.

https://restindia.herokuapp.com/admin/add/state

Request Header:

headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {AuthToken}"
}

Request Body:

{
  "iso3166code": String,
  "code": String,
  "name": String,
  "capital": String,
  "largestCity": String,
  "divisions": Array of Strings,
  "districts": Number,
  "subdivisions": Number,
  "blocks": Number,
  "area": Number,
  "literacy": Number,
  "sexRatio": Number,
  "population": Number,
  "officialWebsite": String,
  "censusYear": Number,
  "emblem": String,
  "languages": Array of Strings,
  "neighbours": Array of Strings
}

Add District

method: POST

Add a new District.

https://restindia.herokuapp.com/admin/add/district

Request Header:

headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {AuthToken}"
}

Request Body:

{
  "districtCode": Number,
  "name": String,
  "state": String,
  "division": String,
  "subdivisions": Array of Strings,
  "blocks": Array of Strings,
  "area": Number,
  "population": Number,
  "literacy": Number,
  "sexRatio": Number,
  "censusYear": Number,
  "officialWebsite": String
}

Updation

Update and Modify Exisiting Data of States and Districts.

Update State

method: PATCH

Update an existing State Data.

https://restindia.herokuapp.com/admin/update/{state}

Request Header:

headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {AuthToken}"
}

Request Body: Please Refer Add State's Request Body.

Update District

method: PATCH

Update an existing District Data.

https://restindia.herokuapp.com/admin/update/{state}/{district}

Request Header:

headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {AuthToken}"
}

Request Body: Please Refer Add District's Request Body.

Password Reset

Password Reset Initiation

method: POST

Send a POST Request to this URL, to get Reset Token.

https://restindia.herokuapp.com/admin/reset-password/init

Request Body:

{
  "email": "vsinha@test.com"
}

Response JSON:
User should get a RESET Link/Token to their Registered Email.

{
  "message": "Password Reset URL is sent to your mail: [success]. Please follow the instructions.",
  "status": 200
}

Password Reset Submission

method: POST

User should have a Unique URL from the previous Request in the given format.

https://restindia.herokuapp.com/admin/reset-password/{userId}/{resetToken}

Send a POST Request to the Unique URL Endpoint with your Email and new Password.

Request Body:

{
  "email": "vsinha@test.com",
  "newPassword": "newPassword#644"
}

Reponse Body:

{
  "email": "vsinha@test.com",
  "message": "Password updated Successfully!",
  "status": 200
}

About

method: GET

Get the information about API Developers, Contributors and more.

https://restindia.herokuapp.com/about

Acknowledgments

REST INDIA Restful API is developed and maintained by Mitanshu Kumar with help from its contributors.

Design and Inspiration: REST Countries API
UI Template by: Flatdoc

Github (@mitanshukr)
Linkedin (@mitanshukr)
Twitter (@mitanshukr)

License

Mozilla Public License MPL 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
controllers		controllers
middleware		middleware
models		models
public		public
routes		routes
utilities		utilities
.travis.yml		.travis.yml
LICENSE		LICENSE
Procfile		Procfile
Readme.md		Readme.md
app.js		app.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json

License

mitanshukr/restindia

Folders and files

Latest commit

History

Repository files navigation

REST INDIA

Data Endpoints

All

All States

All Districts

State

District

General Search

State Specific Search

Query Parameters

Regex Search

Search by Name

Search by Languages

Search by Neighbours

Search by Division

Sort Response

Filter Response

Pagination

Admin Endpoints

Authentication

Signup

Login

Insertion

Add State

Add District

Updation

Update State

Update District

Password Reset

Password Reset Initiation

Password Reset Submission

About

Acknowledgments

License

About

Topics

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages