davidofug/missingpersons-api

Missing persons in Uganda Backend

This is a backend for the Missing persons UG which mirrors the official data file at https://github.com/wkambale/missingpersons/blob/main/data.json

How to setup

It's a Laravel Project so the defaults apply and the requirements are:

PHP 8.2
MySQL 5.7 or 8.x

API Usage

The api base url is https://dashboard.missingpersonsug.org/api/

Victims

The list of victims https://dashboard.missingpersonsug.org/api/victims

Example

GET https://dashboard.missingpersonsug.org/api/victims

{
      "data": [
        {
            "id": 1,
            "name": "Jean Namukasa",
            "nickname": "Mama Jean",
            "gender": "Female",
            "x_handle_full": "https:://x.com/jean",
            "x_handle": "@jean",
            "photo_url": "https://dashboard.missingpersonsug.org/media/reign_maulana.jpg",
            "status": "Arrested",
            "holding_location": "Jinja Road Police Station ",
            "security_organ": "Police",
            "status_date": "Wed, Jul 24, 2024 9:30 AM",
            "notes": "Was taken away in a drone"
        }
      ]
}

Limiting returned items

You can use the per_page URL param to change the number of items returned in a request

Example
- Retrieve 25 items
  
  GET https://dashboard.missingpersonsug.org/api/victims?per_page=25
- Retrieve 10 items
  
  GET https://dashboard.missingpersonsug.org/api/victims?per_page=10
Sorting items

You can sort the returned items by name in ascending or descending order

Use the sort URL param with either name or -name in the value

Examples:
- Ascending order
  
  GET https://dashboard.missingpersonsug.org/api/victims?sort=name
- Descending order
  
  GET https://dashboard.missingpersonsug.org/api/victims?sort=-name
Pagination is also provided under the links and meta elements providing counts of the records, which page a user is on etc

"links": {
    "first": "https:\/\/missingpersons.test\/api\/victims?page=1",
    "last": "https:\/\/missingpersons.test\/api\/victims?page=3",
    "prev": null,
    "next": "https:\/\/missingpersons.test\/api\/victims?page=2"
  },
    
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https:\/\/missingpersons.test\/api\/victims?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https:\/\/missingpersons.test\/api\/victims?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https:\/\/missingpersons.test\/api\/victims?page=3",
        "label": "3",
        "active": false
      },
      {
        "url": "https:\/\/missingpersons.test\/api\/victims?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https:\/\/missingpersons.test\/api\/victims",
    "per_page": 50,
    "to": 50,
    "total": 125
  }

Status

The available status values, at https://dashboard.missingpersonsug.org/api/status

{
    "data": [
        "Missing",
        "Arrested",
        "Fallen",
        "Kidnapped",
        "Found",
        "Unknown",
        "Remanded",
        "Released"
    ]
}

Gender

The available gender values, at https://dashboard.missingpersonsug.org/api/gender

{
    "data": [
        "Male",
        "Female"
    ]
}

Holding Locations

The locations at which different actions happened, at https://dashboard.missingpersonsug.org/api/holding-locations

{
    "data": [
        {
            "id": 1,
            "name": "Unknown",
            "description": null,
            "officer_in_charge": null,
            "location_pin": null
        }
    ]
}

Security Organs

The security organs which were involved with the victims, at https://dashboard.missingpersonsug.org/api/security-organs

{
    "data": [
        {
            "id": 1,
            "name": "Unknown",
            "description": null
        }
    ]
}

Victim Statistics

This is a summary of statistics on the victims at https://dashboard.missingpersonsug.org/api/victim-statistics

{
    "data": {
        "gender": {
            "Male": 102,
            "Female": 23
        },
        "status": {
            "Released": 17,
            "Remanded": 80,
            "Arrested": 27,
            "Missing": 1
        },
        "security_organs": {
            "Police": 120,
            "Joint Forces": 4,
            "Unknown": 1
        },
        "holding_locations": {
            "Luzira Prison": 76,
            "Unknown": 24,
            "Kampala CPS": 3,
            "Parliamentary Avenue Police Station": 2,
            "Kiira Road Police Station": 1,
            "Kitalya": 1,
            "Jinja Road Police Station": 1,
            "Natete Police Station": 1
        }
    }
}

Filtering

The API supports Associative Array notation to filter.

Use the filter[key] URL param to return specific items

Where the key can be replaced with status or holding_location_id

filter[key] supports one of the following options.
- status: filter[status] = Remanded or Arrested or Missing or Released or Fallen
- holding_location_id: filter[holding_location_id] = 1
Examples:
- Filter by status
  
  Remanded
  
  GET https://dashboard.missingpersonsug.org/api/victims?filter[status]=Remanded
  
  Arrasted
  
  GET https://dashboard.missingpersonsug.org/api/victims?filter[status]=Arrested
- Filter by Holding Location
  
  Holding Location
  
  GET https://dashboard.missingpersonsug.org/api/victims?filter[holding_location_id]=1