pygeoquery 0.1.6

Description:

pygeoquery 0.1.6

pygeoquery



Perform geospatial queries on a Firestore database with ease.
pygeoquery allows you to retrieve documents within a certain radius of a given geographic point. It utilizes geohashes for efficient querying.
Features

query Firestore collections by geographic proximity.
efficiently filter and retrieve documents within a specified radius.
flexible and customizable query building.
utilizes geohashes for high-performance geospatial queries.
supports both synchronous and asynchronous Firestore clients.

Installation
You can install the library using pip:
pip install pygeoquery

Prerequisites
Before using this library, ensure that each document in the searched Firestore collection includes a field called "geohash" containing a geohash value generated from the geographical coordinates. This geohash field is essential for the library to perform accurate geospatial queries.

To generate geohashes, you can use Python libraries such as:

pygeohash: Provides functions for decoding and encoding geohashes.
geohashr: Just another Python geohashing library.

Usage


Initialize Firebase
from firebase_admin import initialize_app, credentials
from google.cloud import firestore


# Initialize Firebase
cred = credentials.Certificate("path/to/your/serviceAccountKey.json")
initialize_app(cred, {"projectId": "your-project-id"})



Create Firestore client
# Synchronous client
db = firestore.Client()

or
# Asynchronous client
db = firestore.AsyncClient()



Define callback functions
# Define a GeoPointFromCallback
def geopoint_from_callback(data):
return data.get("location") # Replace with your data structure

# Define query builder callback function (optional). This function allows you to customize your query.
def query_builder_callback(query):
return query.where("property", "==", "value") # Customize your query



Create a GeoCollectionReference or GeoAsyncCollectionReference
# Create a GeoCollectionReference
geocollection = GeoCollectionReference(db.collection("your_collection"))

or
# Create a GeoAsyncCollectionReference (asynchronous client only)
geocollection = GeoAsyncCollectionReference(db.collection("your_collection"))



Fetch documents within a radius of a GeoPoint
# Fetch documents within a radius of a GeoPoint
center_point = GeoPoint(latitude, longitude)
radius_km = 10.0

result = geocollection.fetch_within(
center_point,
radius_km,
geopoint_from_callback,
query_builder_callback
)

# Process the retrieved documents
for document in result:
print(document)

If you are using the asynchronous client, use the await keyword to wait for the result.
result = await geocollection.fetch_within(
center_point,
radius_km,
geopoint_from_callback,
query_builder_callback
)



Acknowledgments
This project is inspired by the geoflutterfire_plus Flutter module by Kosuke Saigusa, which provides similar geospatial querying functionality for Firestore databases in the Flutter framework.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Please read CONTRIBUTING.md for details on my code of conduct, and the process for submitting pull requests to me.
Contact
If you have questions or need assistance, feel free to contact me.
Happy querying!