crossfire: Download spatial data sets from crossfire project
Project description
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 DataFrame
s:
$ pip install crossfire[df]
If you want to have access to the data as GeoPandas GeoDataFrame
s:
$ 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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for crossfire-1.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c28c251995e48423bf55e3cb4488f9cc6131a73e71f9e1e8f1235b01b4b7a5bb |
|
MD5 | f65044e23a1cf5778b0fb3b382286402 |
|
BLAKE2b-256 | 162bbb09d83f66c4838bcc8a9b9c8641eac2c17b0d9fb791acf0a76e79d05a9f |