Skip to content

API Specification

geohacker edited this page Sep 19, 2014 · 55 revisions

API endpoints are broadly classified based on the Entities: (Note: the URL structure is not very well thought. We can always change it. Unless otherwise noted, all response is JSON.) We are sticking to how the Twitter API is and following some pagination aspects of WorldBank API.

Schools

1. GET /api/v:version/schools/list. Returns 50 school name and IDs. Paginated.

Query parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • page. Optional. Default 1.
  • per_page. Optional. Default 50. If 0, fetches all.
  • bbox. Optional.
  • type. Optional. 'all', 'schools', 'preschools'. Default is 'all'.
  • admin1= or admin2= or admin3=. Optional.

Pagination - specify page number in the response.

Response - {'page': 1, 'count': 500, 'next': 'url', 'previous': 'url, 'features': [schools]}

2. GET /api/v:version/schools/info. Returns following for 50 schools. Paginated.

Query parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • page. Optional. Default 1.
  • bbox. Optional
  • type. Optional. 'all', 'schools', 'preschools'. Default is 'all'.
  • admin1= or admin2= or admin3=. Optional.

Pagination - specify page number in the response.

Response - {'page': 1, 'total': 500, 'schools': [schools]}

  • KLP ID
  • DISE Code
  • District
  • 'admin1/2/3': {'id':, 'name':, 'type':<'district'/'block/project'/'cluster/circle'>}
  • Coordinates
  • Type
  • Management
  • Category
  • Medium of Instruction
  • Gender
  • Address
  • Landmark
  • Identifiers
  • Buses
  • Photos # url seems to be md5 of something
  • MLA Constituency
  • MLA Details # what details
  • MP Constituency
  • MP Details # what details
  • Ward
  • Number of Boys
  • Number of Girls
  • Facilities - Computers, Library, Volunteer, Playground.
  • Corporator Details # where to get it?

3. GET /api/v:version/schools/dise/:year. Returns all the DISE variables. Paginated

Query parameters

  • format. Optional (CSV, JSON). Default JSON.
  • page. Optional. Default 1.
  • bbox. Optional
  • admin1= or admin2= or admin3=. Optional.

Pagination - specify page number in the response.

4. GET /api/v:version/schools/school/:id. Return everything in 2 for a particular school.

Query parameters

  • format. Optional (CSV, JSON). Default JSON.

5. GET /api/v:version/schools/bounds/:bounds. Return everything in 2 for all schools within the bounding box.

6. GET /api/v:version/schools/school/:id/demographics. Return the following for a particular school. Optional Query Parameter: year. Defaults to the latest year in the database.

  • Gender
  • Academic Year
  • Number of Girls
  • Number of Boys
  • Number of Students # can be calculated
  • Number of Girls in DISE
  • Number of Boys in DISE
  • Number of Students in DISE # can be calculated
  • Medium of Instruction
  • Managemennt
  • Mother Tongue Profile - "school_mt_tb": {"Urdu": 3, "Others": 0, "Tamil": 4, "Telugu": 2, "Kannada": 79}

7. GET /api/v:version/schools/school/:id/programmes. Return the following

  • Assessments - "assessments": "Remedial_Math-Level2|2008|3|Akshara Foundation,English|2010|15|Akshara Foundation,Reading|2006|1|Akshara Foundation" - @meghaklp help us make sense of this please?

8. GET /api/v:version/schools/school/:id/finance.

  • School Grant (SG)
  • Teacher Learning Material Grant (TLM)
  • School Maintenance Grant (SMG)
  • SG Expenditure in DISE
  • TLM Expenditure in DISE
  • Classroom Count - string (example - "With more than 3 classrooms") @meghaklp need clarity.
  • Teacher Count
  • Type of School - upper primary/lower primary.
  • SG Recieved in DISE
  • TLM Recieved in DISE

9. GET /api/v:version/schools/school/:id/infrastructure

  • Number of Girls
  • Number of Boys
  • Student Count
  • Teacher Count
  • Number of books in DISE
  • Lowest Class
  • Highest Class
  • Classroom count
  • Type
  • Status
  • DISE RTE details
    • Mid-day meal facilities
      • Number of days meals were served last year.
      • Number of boys opting for meals
      • Number of girls opting for meals
      • Number of meals served last year
    • SDMC Detials
      • Number of female Local leaders
      • Number of male Local leaders
      • Number of male members
      • Number of male parent-members
      • Has the SDMC been constituted?
      • Number of meetings held last year
      • Number of female members
  • DISE Facility
    • Toilet Facilities
      • Has Common Toilets
      • Has Separate Toilets for Girls
    • Basic Infrastructure (yes/no)
      • Is in a Rent-free Pucca Building
      • Has a ramp for disabled children
      • Has a Playground
      • Has Secure Boundary walls
      • Has a Separate Room for the Head Master
      • Has Classrooms That Need No Repairs
      • Has Electricity Supply
    • Learning Environment
      • Has Blackboards for all Classrooms
      • Has a Computer Lab
      • Has a Library with Books
    • Nutrition and Hygiene
      • Has Drinking Water Facilities
      • Has Mid-day Meal facility
      • Had a medical camp in the previous year

10. GET /api/v:version/schools/school/:id/library

  • Library Infrastructure (This is from the libinfra DB/View)
  • Library Type (Hub or Spoke)
    • Status of the Library
    • Number of Chairs
    • Number of Tables
    • Number of Racks
    • Number of Books
    • Number of Computers
    • Number of UPS(s)
  • Library Reading Patterns (This is from the Library DB/VW, This is a 3D matrix of data, not sure how to describe this)
  • Number of books borrowed / read per level (GROWBY, ie, Green, Red... Green being lowest level of difficulty) per month per class
    • Number of books borrowed / read per language per month per class
    • Number of books in the library as per DISE (We don't show this today, but we could)

Boundary

1. GET /api/v:version/boundary/admin1. Returns all admin1 boundaries.

Query Parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • type. Optional. 'all', 'schools', 'preschools'. Default is 'all'.

Response

  • Boundary ID.
  • Boundary Name.
  • Type. (either 'preschool' or 'school')

2. GET /api/v:version/boundary/admin1/:id/admin2. Returns all blocks in the district.

Query Parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • type. Optional. 'all', 'schools', 'preschools'. Default is 'all'.

Response

  • Boundary ID.
  • Boundary Name.
  • Type. (either 'preschool' or 'school')

3. GET /api/v:version/boundary/admin1/:id/admin3. Returns all clusters in the district.

Query Parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • type. Optional. 'all', 'schools', 'preschools'. Default is 'all'.

Response

  • Boundary ID.
  • Boundary Name.
  • Type. (either 'preschool' or 'school')

4. GET /api/v:version/boundary/admin2. Returns all blocks.

Query Parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • type. Optional. 'all', 'schools', 'preschools'. Default is 'all'.

Response

  • Boundary ID.
  • Boundary Name.
  • Type. (either 'preschool' or 'school')

5. GET /api/v:version/boundary/admin2/:id/admin3. Returns all clusters in the block

Query Parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • type. Optional. 'all', 'schools', 'preschools'. Default is 'all'.

Response

  • Boundary ID.
  • Boundary Name.
  • Type. (either 'preschool' or 'school')

6. GET /api/v:version/boundary/admin3. Returns all clusters.

Query Parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • type. Optional. 'all', 'schools', 'preschools'. Default is 'all'.

Response

  • Boundary ID.
  • Boundary Name.
  • Type. (either 'preschool' or 'school')

7. GET /api/v:version/boundary/admin/:id. Returns the specific boundary (either admin1, 2 or 3).

Query Parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • geometry. yes or no.

Response

  • Boundary ID.
  • Boundary Name.
  • Type. (either 'preschool' or 'school')

8. GET /api/v:version/boundary/parliament/:id. Returns the specific boundary (either admin1, 2 or 3).

Query Parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • geometry. yes or no.

Response

  • Parliament ID.
  • Parliament Name.

9. GET /api/v:version/boundary/assembly/:id. Returns the specific boundary (either admin1, 2 or 3).

Query Parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • geometry. yes or no.

Response

  • Assembly ID.
  • Assembly Name.

9. GET /api/v:version/boundary/pincode/:id. Returns the specific boundary (either admin1, 2 or 3).

Query Parameters

  • format. Optional (CSV, GeoJSON). Default GeoJSON.
  • geometry. yes or no.

Response

  • Pincode ID.
  • Pincode.

Geo.

Query parameters

  • geometry. Optional (yes, no). Default no. Specifies if the geometry (point, line, polygon) should be returned.
  • format. Optional (CSV, GeoJSON). If geometry=yes, return GeoJSON. Default JSON.

1. GET /api/v:version/geo/admin1/:school_id - Returns the district where school belongs.

2. GET /api/v:version/geo/admin2/:school_id - Returns the block where school belong.

3. GET /api/v:version/geo/admin3/:school_id - Returns the cluster where school belong.

4. GET /api/v:version/geo/pincode/:school_id - Returns the pincode where school belong.

5. GET /api/v:version/geo/parliament/:school_id - Returns the MP constituency.

6. GET /api/v:version/geo/assembly/:school_id - Returns the MLA constituency.

## Students

## Teachers

Programmes

Assessments

Share Your Story

1. GET /api/v:version/stories/:school_id/questions - Returns all the questions for that specific type of school.

Query parameters

  • source. (web, ivrs, csv, mobile). Optional. Default web.

2. POST /api/v:version/stories/:school/answers - Send a JSON with question ID and answers. Return the story object.

3. GET /api/v:version/stories/ - Return the total number of stories, comments of each story if available for the school ID.

Query parameters

  • school. School ID for the story.
  • verified. Values - True, False. If this parameter is not mentioned, the API will return all the stories for that school.

4. GET /api/v:version/stories/verify - Return all the stories that are not verified.

5. POST /api/v:version/stories/:id/verify - Set the story as verified.

Users.

1. POST /user/users : Creates a new user

2. GET /user/users : lists users (only for admin)

3. GET /user/profile : gets user's own profile

4. PATCH /user/profile : edit profile

5. POST /user/signin : Login

6. POST /user/signout : Logout

7. GET /user/resend_verification : Re-send email verification

8. GET /user/resend_pin : Re-send SMS PIN

9. POST /user/verify_pin : post SMS PIN for verification

10. Separate view for verify email (not part of API)

Volunteer / Donate

For Organization Managers:

  1. List Volunteer Requests for own Organization.
  2. List Donation Requests for own Organization.
  3. Add Volunteer Request
  4. Add Donation Request
  5. Edit Volunteer Request
  6. Edit Donation Request
  7. Delete Volunteer Request
  8. Delete Donation Request
  9. List Signed-up Volunteers.
  10. List Signed-up Donators
  11. Change "status" of User for a Volunteer Request (mark completed, etc.)
  12. Change "status" of User for Donation Request

For users:

  1. Sign up for Volunteer Request
  2. Sign up to Donate for Donation Request
  3. See Volunteer Requests signed up for
  4. See Donations signed up for

Reports.

  1. Fetch reports based on hierarchy

Data Exports

1. Schools

GET /api/v:version/data/schools - Return all schools with all information in CSV format.

2. SSLC

GET /api/v:version/data/sslc - Return anonymised SSLC results.

  • year. Optional. Default latest.

3. DISE

GET /api/v:version/data/dise - Return all DISE variables in CSV format.

  • year. Optional. Default latest.

4. Partner data

GET /api/v:version/data/:partner - Return anonymised partner data in CSV.

You can’t perform that action at this time.