# Introduction

The insertion and the filteration API for geolocations

#### Headers
`Content-Type`,`Accept` must be `application/json`

#### Authentication
No authentication implemented

#### Error Codes
Try to check the raw data if its having `errors` even if the `status_code` is 200.

## API

Application url: `https://alpha.ahamtech.in/`

### 1. Import Geolocations from CSV file with link

method `POST`
endpoint: `/api/import`

Import Geolocations from a csv file and insert in DB

| Attribute | Options | Type | Mandatory | Description |
| -------------------- | --------- |--------- | --------- | ---------------------- |
| `url` | https://dl.dropboxusercontent.com/s/8i01hgy09o6yikx/sample_100.csv?dl=0 | String |YES | url for the csv file to download |
| `importer_type` | `async`, `sync` | String |YES | whether to insert the data concurrently or sequentially |

Prefer `async` only if the poolsize is more, else insertions will face timeouts.

#### Sample Requests

{
    "url": "https://dl.dropboxusercontent.com/s/pbmcq77le04q76y/sample.csv?dl=0",
    "importer_type": "async"
}

#### Sample Responses

{
  "data": {
    "discarded_count": 21,
    "download_time_elasped": 756,
    "file_path": "/tmp/f-1633430269-1-1m6h6eg",
    "id": 2,
    "inserted_count": 84,
    "inserted_time_elapsed": 15571,
    "status": "completed",
    "time_unit": "millisecond"
  }
}

{
    "errors": {
        "url": [
            "is missing a scheme (e.g. https)"
        ]
    }
}

### 2. Get Geolocations by IP address

method `GET`
endpoint `/api/geo_locations/{{ip_address}}`

Gets the list of Geolocations based on the ip_address provided

#### Sample Responses

{
    "data": [
        {
            "city": "Gradymouth",
            "country": "Saudi Arabia",
            "country_code": "TL",
            "id": "a4c2c5e6-5360-4ef7-8e6e-b5bae074f3dd",
            "ip_address": "70.95.73.73",
            "latitude": -49.16675918861615,
            "longitude": -86.05920084416894,
            "mystery_value": "2559997162"
        },
        {
            "city": "Gradymouth",
            "country": "Saudi Arabia",
            "country_code": "TL",
            "id": "80f25b15-e821-4a63-8fec-27c2c5c95c3b",
            "ip_address": "70.95.73.73",
            "latitude": -49.16675918861615,
            "longitude": -86.05920084416894,
            "mystery_value": "2559997162"
        }
    ]
}

{
    "data": []
}

### 3. Query Geolocations

method `POST`
endpoint: `/api/geo_locations/query`

Query the Geolocations table with a list of variables may be based on city or country or any other

List of various filters available for querying.

| Attribute | Type | Mandatory | Description |
| -------------------- | --------------- | --------- | ---------------------- |
| `has_ips` | array of string | NO | array of ip_address |
| `has_cities` | array of string | NO | array of city |
| `has_countries` | array of string | NO | array of country |
| `has_country_codes` | array of string | NO | array of country_code |
| `has_mystery_values` | array of string | NO | array of mystery_value |
| `has_latitudes` | array of float | NO | array of latitude |
| `has_longitudes` | array of float | NO | array of longitude |

Note
* If NO attribute is sent, it returns the all the geolocations
* Can also combine as many as filters

#### Sample Requests

{
    "has_cities": ["DuBuquemouth"],
    "has_countries": ["Nepal"]
}

{
    "has_ips": ["200.106.141.15","160.103.7.140"]
}

#### Sample Responses

{
    "data": [
        {
            "city": "Gradymouth",
            "country": "Saudi Arabia",
            "country_code": "TL",
            "id": "a4c2c5e6-5360-4ef7-8e6e-b5bae074f3dd",
            "ip_address": "70.95.73.73",
            "latitude": -49.16675918861615,
            "longitude": -86.05920084416894,
            "mystery_value": "2559997162"
        },
        {
            "city": "Gradymouth",
            "country": "Saudi Arabia",
            "country_code": "TL",
            "id": "80f25b15-e821-4a63-8fec-27c2c5c95c3b",
            "ip_address": "70.95.73.73",
            "latitude": -49.16675918861615,
            "longitude": -86.05920084416894,
            "mystery_value": "2559997162"
        }
    ]
}

{
    "data": []
}

### 4. List All Geolocations

method `GET`
endpoint `/api/geo_locations`

Lists out all the Geolocations from DB

#### Sample Responses

{
    "data": [
        {
            "city": "Gradymouth",
            "country": "Saudi Arabia",
            "country_code": "TL",
            "id": "a4c2c5e6-5360-4ef7-8e6e-b5bae074f3dd",
            "ip_address": "70.95.73.73",
            "latitude": -49.16675918861615,
            "longitude": -86.05920084416894,
            "mystery_value": "2559997162"
        },
        {
            "city": "Gradymouth",
            "country": "Saudi Arabia",
            "country_code": "TL",
            "id": "80f25b15-e821-4a63-8fec-27c2c5c95c3b",
            "ip_address": "70.95.73.73",
            "latitude": -49.16675918861615,
            "longitude": -86.05920084416894,
            "mystery_value": "2559997162"
        }
    ]
}

{
    "data": []
}

### 5. Get Assignment Stats

method `GET`
endpoint `/api/assignments/:id`

We save all the statistics for all the files in the db.
It is accessed by a ID.

#### Sample Responses

{
  "data": {
    "discarded_count": 21,
    "download_time_elasped": 536,
    "file_path": "/tmp/f-1633425286-38829-12e7h94",
    "id": 6,
    "inserted_count": 84,
    "inserted_time_elapsed": 98,
    "status": "completed",
    "time_unit": "millisecond"
  }
}