crossfire Python client

crossfire is a package created to give easier access to Fogo Cruzado'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.

Requirements

• Python 3.9 or newer

Install

$ pip install crossfire

If you want to have access to the data as Pandas DataFrames:

$ pip install crossfire[df]

If you want to have access to the data as GeoPandas GeoDataFrames:

$ pip install crossfire[geodf]

Authentication

To have access to the API data, registration is required.

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

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.

Usage

List of states covered by the project

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

from crossfire import states


states()

It is possible to get results in DataFrae:

states(format='df')

List of cities covered by the project

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

from crossfire import cities


cities()

It is possible to get results in DataFrae:

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:

from crossfire import occurrences


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

It is possible to get results in DataFrae:

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

Or as GeoDataFrame:

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:

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')

Asynchronous use with asyncio

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 is the creator of the Python package. This implementation was funded by CYTED project number 520RT0010 redGeoLIBERO.

Contributors

• @sergiospagnuolo
• @silvadenisson
• @cuducos