Metadata-Version: 2.1
Name: crossfire
Version: 1.0.0
Summary: crossfire: Download spatial data sets from crossfire project
Home-page: https://fogocruzado.org.br/
Author: Felipe Barros
Author-email: felipe.b4rros@gmail.com
Requires-Python: >=3.9,<3.13
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Provides-Extra: df
Provides-Extra: geodf
Requires-Dist: geopandas (>=0.13.2,<0.14.0) ; extra == "geodf"
Requires-Dist: httpx (>=0.25.0,<0.26.0)
Requires-Dist: pandas (>=2.1.1,<3.0.0) ; extra == "df" or extra == "geodf"
Requires-Dist: python-decouple (>=3.5,<4.0)
Requires-Dist: tqdm (>=4.66.1,<5.0.0)
Project-URL: Repository, https://github.com/felipesbarros/crossfire
Description-Content-Type: text/markdown

<div style="text-align: center">
<img src="https://raw.githubusercontent.com/voltdatalab/crossfire/master/crossfire_hexagono.png" width="130px" alt="hexagon crossfire"/>

# `crossfire` Python client
</div>

`crossfire` is a package created to give easier access to [Fogo Cruzado](https://fogocruzado.org.br/)'s datasets, which is a digital collaborative platform of gun shooting occurrences in the metropolitan areas of Rio de Janeiro and Recife.

The package facilitates data extraction from [Fogo Cruzado's open API](https://api.fogocruzado.org.br/).

## Requirements

* Python 3.9 or newer

## Install

```console
$ pip install crossfire
```

If you want to have access to the data as [Pandas `DataFrame`s](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html):

```console
$ pip install crossfire[df]
```

If you want to have access to the data as [GeoPandas `GeoDataFrame`s](https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.html):

```console
$ pip install crossfire[geodf]
```

## Authentication

To have access to the API data, [registration is required](https://api.fogocruzado.org.br/sign-up).

The `email` and `password` used in the registration can be configured as `FOGOCRUZADO_EMAIL` and `FOGOCRUZADO_PASSWORD` environment variables in a `.env` file:

```env
FOGOCRUZADO_EMAIL=your@mail.com
FOGOCRUZADO_PASSWORD=YOUR_PASSWORD
```

If you prefer _not_ to use these environment variables, you can still use the credentials [when instantiating a client](#custom-client).

## Usage

### List of states covered by the project

Get all states with at least one city covered by the Fogo Cruzado project:

```python
from crossfire import states


states()
```

It is possible to get results in `DataFrae`:

```python
states(format='df')
```

### List of cities covered by the project

Get cities from a specific state covered by the Fogo Cruzado project.

```python
from crossfire import cities


cities()
```

It is possible to get results in `DataFrae`:

```python
cities(format='df')
```

#### `Cities` parameters

| Name | Required | Description | Type | Default value | Example |
|---|---|---|---|---|---|
| `state_id` | ❌ | ID of the state | string | `None` | `'b112ffbe-17b3-4ad0-8f2a-2038745d1d14'` |
| `city_id` | ❌ | ID of the city | string | `None` | `'88959ad9-b2f5-4a33-a8ec-ceff5a572ca5'` |
| `city_name` | ❌ | Name of the city | string | `None` | `'Rio de Janeiro'` |
| `format` | ❌ | Format of the result | string | `'dict'` | `'dict'`, `'df'` or `'geodf'` |


### Listing occurrences

To get shooting occurrences from Fogo Cruzado dataset it is necessary to specify a state id in `id_state` parameter:

```python
from crossfire import occurrences


occurrences('813ca36b-91e3-4a18-b408-60b27a1942ef')
```

It is possible to get results in `DataFrae`:

```python
occurrences('813ca36b-91e3-4a18-b408-60b27a1942ef', format='df')
```

Or as `GeoDataFrame`:

```python
occurrences('813ca36b-91e3-4a18-b408-60b27a1942ef', format='geodf')
```

#### `Occurrences` parameters

| Name | Required | Description | Type | Default value | Example                                                                                                                        |
|---|---|---|---|---|--------------------------------------------------------------------------------------------------------------------------------|
| `id_state` | ✅ | ID of the state | string | `None` | `'b112ffbe-17b3-4ad0-8f2a-2038745d1d14'`                                                                                       |
| `id_cities` | ❌ | ID of the city | string or list of strings | `None` | `'88959ad9-b2f5-4a33-a8ec-ceff5a572ca5'` or `['88959ad9-b2f5-4a33-a8ec-ceff5a572ca5', '9d7b569c-ec84-4908-96ab-3706ec3bfc57']` |
| `type_occurrence` | ❌ | Type of occurrence | string | `'all'` | `'all'`, `'withVictim'` or `'withoutVictim'`                                                                                   |
| `initial_date` | ❌ | Initial date of the occurrences | string, `date` or `datetime` | `None` | `'2020-01-01'`, `'2020/01/01'`, `'20200101'`, `datetime.datetime(2023, 1, 1)` or `datetime.date(2023, 1, 1)`                   | 
| `final_date` | ❌ | Final date of the occurrences | string, `date` or `datetime` | `None` | `'2020-01-01'`, `'2020/01/01'`, `'20200101'`, `datetime.datetime(2023, 1, 1)` or `datetime.date(2023, 1, 1)`                   |
| `max_parallel_requests` | ❌ | Maximum number of parallel requests to the API | int | `16` | `32`                                                                                                                           |
| `format` | ❌ | Format of the result | string | `'dict'` | `'dict'`, `'df'` or `'geodf'`                                                                                                  |


### Custom client

If not using the environment variables for authentication, it is recommended to use a custom client:

```python
from crossfire import Client


client = Client(email="fogo@cruza.do", password="Rio&Pernambuco") # credentials are optional, the default are the environment variables
client.states()
client.cities()
client.occurrences('813ca36b-91e3-4a18-b408-60b27a1942ef')
```

### Uso assíncrono com `asyncio`

```python
from crossfire import AsyncClient


client = AsyncClient()  # credentials are optional, the default are the environment variables
await client.states()
await client.cities()
await client.occurrences('813ca36b-91e3-4a18-b408-60b27a1942ef')
```

## Credits

[@FelipeSBarros](https://github.com/FelipeSBarros) is the creator of the Python package. This implementation was funded by CYTED project number `520RT0010 redGeoLIBERO`.

### Contributors

* [@sergiospagnuolo](https://github.com/sergiospagnuolo)
* [@silvadenisson](https://github.com/silvadenisson)
* [@cuducos](https://github.com/cuducos)

