Django Location API

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 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.