Metadata-Version: 2.4
Name: django-location-api
Version: 0.3.0
Summary: Django package for location services
Project-URL: Homepage, https://github.com/carlosfunk/django-location-api
Author-email: Carl Robben <carl@successmonkey.co.nz>
License-Expression: BSD-3-Clause
License-File: AUTHORS.rst
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: <4,>=3.9
Requires-Dist: django-filter>=21.1
Requires-Dist: django>=4.2
Requires-Dist: djangorestframework-gis>=0.18
Requires-Dist: djangorestframework>=3.13.0
Description-Content-Type: text/x-rst

===================
Django Location API
===================

.. image:: https://github.com/carlosfunk/django-location-api/actions/workflows/ci.yml/badge.svg
        :target: https://github.com/carlosfunk/django-location-api/actions/workflows/ci.yml
        :alt: CI Status

.. image:: https://img.shields.io/pypi/v/django-location-api.svg
        :target: https://pypi.python.org/pypi/django-location-api
        :alt: PyPI Version

.. image:: https://img.shields.io/pypi/pyversions/django-location-api.svg
        :target: https://pypi.python.org/pypi/django-location-api
        :alt: Python Versions

.. image:: https://img.shields.io/badge/django-4.2%20%7C%205.1%20%7C%205.2-44B78B.svg
        :target: https://www.djangoproject.com/
        :alt: Django Versions

.. image:: https://img.shields.io/badge/license-BSD--3--Clause-blue.svg
        :target: https://github.com/carlosfunk/django-location-api/blob/main/LICENSE
        :alt: License

Django package for location services.

* Free software: BSD-3-Clause

Features
--------

* **Dual-app architecture**: Choose between abstract base models or concrete implementations
* **PostGIS integration**: Full GIS support for location data
* **Pluggable models**: Use your own Location model while leveraging our views and serializers
* **REST API**: Complete API endpoints with Django REST Framework
* **Admin integration**: Ready-to-use Django admin interfaces

Requirements
------------

* Python 3.9+
* Django 4.2+
* PostgreSQL with PostGIS extension
* Django REST Framework
* django-rest-framework-gis

Architecture
------------

django-location-api provides two Django apps:

**location_api_core**
    Contains abstract base models (``AbstractBaseLocation``, ``Supplier``, ``SupplierAlias``) 
    that you can inherit from in your own apps. Use this when you want to customize 
    the Location model.

**location_api**
    Contains a concrete ``Location`` model that inherits from ``AbstractBaseLocation``. 
    Use this for quick setup when you don't need customization.

Installation Options
--------------------

Option 1: Using Abstract Models
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Install only the core models and create your own Location model::

    INSTALLED_APPS = [
        ...,
        "rest_framework",
        "rest_framework_gis", 
        "location_api_core",  # Only install core
        "your_app",  # Your app with custom Location model
    ]

In your ``models.py``::

    from location_api_core.models import AbstractBaseLocation

    class YourLocationModel(AbstractBaseLocation):
        # Add your custom fields here
        custom_field = models.CharField(max_length=100)
        
        class Meta:
            ordering = ("name",)

Configure the API to use your model in ``settings.py``::

    LOCATION_API_LOCATION_MODEL = "your_app.YourLocationModel"

Option 2: Using Concrete Models (Quick Start)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use the provided concrete Location model::

    INSTALLED_APPS = [
        ...,
        "rest_framework",
        "rest_framework_gis",
        "location_api_core",  # Core models
        "location_api",       # Concrete Location model
    ]

Quick Start
-----------

1.
  Install using pip::

      pip install django-location-api

  Or using your preferred package manager::

      # Using uv
      uv add django-location-api

      # Using poetry
      poetry add django-location-api

2. Add the required packages to your INSTALLED_APPS (see Installation Options above).

3. Include the location_api URL conf in your project urls.py::

    path("api/", include("location_api.urls")),
    path("api/location/", include("location_api.urls.search")),


4. (Optional) If using abstract models, configure your custom model::

    LOCATION_API_LOCATION_MODEL = "your_app.Location"

5. Run migrations to create the models::

    python manage.py migrate

6. Start the development server and visit the admin site to create locations.

7. Access the API endpoints:
   
   * ``/api/location/`` - List and create locations
   * ``/api/location/{id}/`` - Retrieve, update, delete specific location
   * ``/api/location/search/`` - Search locations

API Usage Examples
------------------

Creating a location via API::

    POST /api/locations/
    {
        "name": "Central Park",
        "point": {
            "type": "Point",
            "coordinates": [-73.965355, 40.782865]
        },
        "country_code": "US",
        "supplier": 1,
        "attributes": {
            "type": "park",
            "area": "843 acres"
        }
    }

Searching locations::

    GET /locations/search/?term=park

Geographic queries (bounding box)::

    GET /api/locations/?in_bbox=-74.0,40.7,-73.9,40.8

Models
------

**AbstractBaseLocation**
    Base abstract model with common location fields:
    
    * ``name`` - Location name
    * ``point`` - PostGIS Point field for coordinates  
    * ``country_code`` - ISO country code
    * ``created/modified`` - Timestamps
    * ``attributes`` - JSON field for additional data
    * ``archived`` - Soft delete flag
    * ``supplier`` - Foreign key to Supplier

**Supplier**
    Represents location suppliers/operators:
    
    * ``name`` - Supplier name
    * Built-in ``identify()`` method for string matching

**SupplierAlias**
    Regex patterns for supplier identification:
    
    * ``regex`` - Pattern for matching
    * ``supplier`` - Foreign key to Supplier

Development
-----------

This project uses `uv <https://docs.astral.sh/uv/>`_ for dependency management
and ships a Docker Compose setup that provides PostgreSQL + PostGIS and the
full test environment.

Install dependencies locally (for formatting / linting only — the test
suite requires PostGIS, which is easiest to get via Docker)::

    uv sync

Run the test suite (45 tests, all under Docker)::

    docker compose run --rm django python ./runtests.py

Run the example projects (see ``examples/`` for walkthroughs)::

    # Basic example (concrete Location model) — http://localhost:8000
    docker compose run --rm django python examples/basic/manage.py migrate
    docker compose up django

    # Custom example (AbstractBaseLocation + extra fields) — http://localhost:8001
    docker compose run --rm -T custom-example python examples/custom/manage.py migrate
    docker compose --profile custom up custom-example

Format and lint::

    uv run invoke format
    uv run invoke lint

Create / update migrations for the concrete ``location_api`` app::

    docker compose run --rm django python examples/basic/manage.py makemigrations location_api

Credits
-------

This package was created with Cookiecutter_ and the `briggySmalls/cookiecutter-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`briggySmalls/cookiecutter-pypackage`: https://github.com/briggySmalls/cookiecutter-pypackage
