Metadata-Version: 2.1
Name: nectaapi
Version: 2.0.0
Summary: Fetch results of various national examinations done in Tanzania
Home-page: https://github.com/vincent-laizer/NECTA-API
Author: Tanzania Programmers (Vincent Laizer)
Author-email: <laizercorp@gmail.com>
License: UNKNOWN
Keywords: python,necta,api,necta api,necta tanzania,tanzania programmers
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Description-Content-Type: text/markdown

# Necta-API
Get a formated data of examination results scrapped from necta results website.

Note this is not an official [NECTA](https://necta.go.tz/) API and is still in development

Current version is `Beta 2.0.0`

This Version comes with a more modular structure compared to the previsious ones 

Developed by [**Tanzania Programmers**](http://tanzaniaprogrammers.com/), written *by Vincent Laizer.*
---

---

## Usage
- [x] Get the package via pip

``` 
    pip install nectaapi 
```

- In any return value **asterisc '*'** indicates that no data could be scrapped

- [x] Get a list of all schools in a given year and exam type.

exam type can be **acsee** or **csee** (for now, more to be added)

```python
    from nectaapi import schools

    data = schools.schools(2017, 'csee') 
```
  the function returns a dictionary in the form

  ```python
  {
      "exam_type": "examamination type",
      "year_of_exam": "year of examination",
      "number_of_schools": "number of schools in this exam and year",
      "schools": [
          {
              "school_name": "school name 1",
              "registration_number":"registration number 1"
          },
          {
              "school_name": "school name 2",
              "registration_number":"registration number 2"
          },
           ...]
  }
  ```

  - [x] Get a highlight of school overal results
  ```python
    from nectaapi import summary

    data = summary.summary(year, examType, schoolNumber)

    # schoolNumber is the schools registration number ie s3881 or s1268
  ```
  the function returns a dictionary in the form
  ```python
    {
        "school_name": "name of school",
        "school_number": "school_number",
        "exam_type": "exam_type",
        "year_of_exam": "year",
        "school_category":"category based on number of students",
        "number_of_students": "total number of students",
        "school_region":"regional location of the school",
        "male_students": "number of male students",
        "female_students": "number of female students",
        "absentees": "number of students who missed the exam",
        "division_one": "number of division one",
        "division_two": "number of division two",
        "division_three": "number of division three",
        "division_four": "number of division four",
        "division_zero":"number of division zero",
        "national_position": "school's national position",
        "regional_position": "school's regional position",
        "total_national_schools":"number of schools national wise",
        "total_regional_schools":"number of schools regional wise",
        "gpa": "school's GPA"
    }
  ```

  - [x] Get a single students results
  ```python
    from nectaapi import student

    results = student.student(year, examType, schoolNumber, studentNumber)

    # student number is the students part of their examination number eg 0040 or 0553
  ```

  The 'student' function returns a dictionary of this form
  ```python
    {
    "examination_number":"students examination number",
    "year_of_exam":"year",
    "exam_type":"exam type",
    "school_name":"name of student's school",
    "gender":"student's gender",
    "division":"students division",
    "points":"grade points",
    "subjects":
            {
                "subject1":"score1",
                "subject2":"score2",
                ...
            }
    }
  ```

- [x] Compare schools performance over a range of years or of just a single school

not present in perivious versions

The parameters of the function are, the start year, end year of comparison, exam type and a list of schools to compare. start year is always less than end year, suppose they are equal a one year comparison is returned

```python
    from nectaapi import comparison
    data = comparison.comparison(start_year, end_year, exam_type,  ["school_number1", "school_number2", ...])
```

It then returns a dictionary with school comparable data like, gpa, national_position and number_of_students in the form

```python
    {
        "year1":{
            "school_number1":{
                "gpa":"",
                "national_position":"",
                "number_of_students":""
            },
            "school_number2":{
                "gpa":"",
                "national_position":"",
                "number_of_students":""
            },
            ...
        },
        "year2":{
            "school_number1":{
                "gpa":"",
                "national_position":"",
                "number_of_students":""
            },
            "school_number2":{
                "gpa":"",
                "national_position":"",
                "number_of_students":""
            },
            ...
        }
        ...
    }
```

As one of my teachers said, **"Academics is one of the 3 areas in life where competition is allowed"** *Mr. H. Masegense*, so don't mind comparing performance of schools over the years

+ comparison module comes with a bonus function to check if a school participated in national examinations of a given type and year. Returns a boolean value

```python
    from nectaapi import comparison
    isPresent = comparison.schoolPresent(year, exam_type, school_number)
```

## What's New
- Bug fixes on the school summary function
- proper handling of the year 2015 where GPA system was used.
    - note, in this year, distinction is counted as division one, merit as division two, credit as division three, pass as division four and fail as division zero.
- school comparison function
- code modularity improvement

---

  check out video tutorial on [YouTube](https://tanzaniaprogrammers.com/nectaapi) for demos.

---

### contributions are awaited for **GitHub repo [NECTA-API](https://github.com/vincent-laizer/NECTA-API)**


