Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

location field with MapInput widget for picking some location

Project description


Build Status Coverage Status PyPI

Simple in use location model and form field with MapInput widget for picking some location. Uses mapbox gl js, flexible map provider API. Fully compatible with bootstrap framework.

Table of contents

Why this?

I was searching for some django location field which uses mapbox and I could use in my project. I didn't find anything which suits my needs in 100% and that is why I created this simple django app. My philosopy was simplicity but I wanted to create complete solution for picking location.

Feel free to open issues, make pull request and request some features or instructions. Let me know if you think it is not flexible enought.

Live demo

Curious how it works and looks like ? See live demo on Demo app uses django-bootstrap4 for a little better looking form fields.


Automatically tested on Travis CI on versions:

  • Django 1.11, 2.0, 2.1, 2.2
  • Python 3.5, 3.6, 3.7

PS. Django 1.11 does not support Python 3.7 anymore.

Browser support

django-mapbox-location-field support all browsers, which are suported by mapbox gl js. Read more here

Databases support

It should work with every spatial and plain (non-spatial) database, that works with django and geodjango.

Versions >1.4.0

Since version 1.4.0 the order of coordinates convention has been changed. Now the order is longitude, latitude. This change has been caused by support for spatial databases. But more user friendly is order latitude, longitude(google maps uses it). That's why coordinates are falsely swapped in frontend and then after POST request in form field are swapped back into longitude, latitude order and saved to database. My conclusion is that the location is falsely swapped in fronend and if you create location without our custom form field or just operate on raw model in backend, you will have to use the longitude, latitude order. Versions before 1.4.0 always uses latitude, longitude order.


Using pip: pip install django-mapbox-location-field


  • Add "mapbox_location_field" to INSTALLED_APPS in your settings file
INSTALLED_APPS += ("mapbox_location_field",)
  • Define MAPBOX_KEY in your settings file. This is vulnerable information which has to be passed to frontend, so it can be easily access by user. To ensure your safety, I would recommend using url restrictions and public scopes. More information on linked websites.
MAPBOX_KEY = "pk.eyJ1IjoibWlnaHR5c2hhcmt5IiwiYSI6ImNqd2duaW4wMzBhcWI0M3F1MTRvbHB0dWcifQ.1sDAD43q0ktK1Sr374xGfw"

PS. This above is only example access token. You have to paste here yours.



    • Just create some model with LocationField.
      from django.db import models
      from mapbox_location_field.models import LocationField
      class SomeLocationModel(models.Model):
          location = LocationField()

    • Just create some model with SpatialLocationField.
      from django.db import models
      from mapbox_location_field.spatial.models import SpatialLocationField
      class SomeLocationModel(models.Model):
          location = SpatialLocationField()
  • Create ModelForm

    from django import forms
    from .models import Location
    class LocationForm(forms.ModelForm):
        class Meta:
            model = Location
            fields = "__all__"

    Of course you can also use CreateView, UpdateView or build Form yourself with mapbox_location_field.forms.LocationField or mapbox_location_field.spatial.forms.SpatialLocationField

  • Then just use it in html view. It can't be simpler! Paste this in your html head:

    {% load mapbox_location_field_tags %}
    {% location_field_includes %}
    {% include_jquery %}
  • And this in your body:

       <form method="post">
            {% csrf_token %}
            <input type="submit" value="submit">
    {{ }}
  • Your form is ready! Start your website and see how it looks. If you want to change something look to the customization section.


In order to change few things you have to use map_attrs dictionary. Default map_attrs looks like this:

default_map_attrs = {
            "style": "mapbox://styles/mapbox/outdoors-v11",
            "zoom": 13,
            "center": [17.031645, 51.106715],
            "cursor_style": 'pointer',
            "marker_color": "red",
            "rotate": False,
            "geocoder": True,
            "fullscreen_button": True,
            "navigation_buttons": True,
            "track_location_button": True,
            "readonly": True,
            "placeholder": "Pick a location on map below",

To change some values, just pass it when you creates model.

from django.db import models
from mapbox_location_field.models import LocationField

class Location(models.Model):
    location = LocationField(map_attrs={"center": [0,0], "marker_color": "blue"})


  • style - <string>, mapbox style url. Read more here.
  • zoom - <int>, map's zoom. Read more here.
  • center - <list> or <tuple> of <float>s, defaults map's center point in [latitude, longitude]
  • cursor_style - <string>, css cursor style. Read more here.
  • marker_color - <string> css color property. Read more here and here.
  • rotate - <bool>, whether you can rotate map with right mouse click or not.
  • geocoder -<bool>, whether geocoder searcher is showed or not.
  • fullscreen_button - <bool>, whether fullscreen button is showed or not.
  • navigation_buttons - <bool>, whether navigation buttons are showed or not.
  • track_location_button - <bool>, whether show my location button is showed or not.
  • readonly - <bool>, whether user can type location in text input
  • placeholder - <string>, text input's placeholder


MapInput widget is fully compatibile with bootstrap library. I can even recommend to use it with django-bootstrap4 or django-crispy-forms.

Admin interface usage

First create some model with location field like in usage section. Then register it in admin interface like this:

from django.contrib import admin
from .models import Location
from mapbox_location_field.admin import MapAdmin, MapAdmin)

In example above, Location is name of your model. Everything from customization section also works in admin interface.


AddressAutoHiddenField is field for storing address. It uses AddressAutoHiddenInput which is hidden and when you place your marker on map, automatically fill itself with proper address. In order to use it just add it to your model. Something like this:

class Location(models.Model):
    location = LocationField()
    address = AddressAutoHiddenField()


  • Django
  • mapbox gl js
  • jquery
  • html and css

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-mapbox-location-field, version 1.4.0
Filename, size File type Python version Upload date Hashes
Filename, size django-mapbox-location-field-1.4.0.tar.gz (16.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page