Strapi Plugin Location

This plugin allows users to create location inputs and store latitude and longitude values as geometry types in a PostGIS database. It also provides functionality to filter items based on their location.

Caution 🖐⚠️

This plugin requires a PostgreSQL database with the PostGIS extension enabled (can be used on that database plugin will enable it for you if it can). Make sure you have a compatible database set up before using this plugin. For development I used postgis docker image from here: https://registry.hub.docker.com/r/postgis/postgis/

⚠️ Filtering by data in relations is not supported.

🙉 What does the plugin do for you?

• ✅ Provides a custom location input field for latitude, longitude, and address data (address, city, state/province, country)
• ✅ Display the location on a map and fine-tune it by moving a marker using drag-and-drop functionality
• ✅ Handles storage of location values as geometry types in a PostGIS database
• ✅ Allows filtering of items based on their location (geo distance)
• ✅ Enables filtering by address fields: city, state/province, country, countryCode, and address text
• ✅ Supports combining geo search with state/province (e.g. “within 50km and in California”)

🧑‍💻 Installation

1. Install the package with your preferred package manager:

   npm install @d3levvv/strapi-plugin-location
   # or
   yarn add @d3levvv/strapi-plugin-location

2. Create or modify config/plugins.js (or config/plugins.ts) and add:

module.exports = ({ env }) => ({
	"location-plugin": {
		enabled:  true,
    config: {
      googleMapsKey: env('your_google_maps_api_key_env_here'),
    }
	},
});

3. Rebuild the Strapi admin so the plugin appears in the admin UI:

   npm run build
   # or
   yarn build

4. Extend config/middlewares.js (or config/middlewares.ts) as in the example below:

export default [
    "strapi::logger",
    "strapi::errors",
    {
        name: "strapi::security",
        config: {
            contentSecurityPolicy: {
                useDefaults: true,
                directives: {
                    "connect-src": ["'self'", "https:"],
                    "script-src": [
                        "'self'",
                        "unsafe-inline",
                        "https://maps.googleapis.com",
                    ],
                    "media-src": [
                        "'self'",
                        "blob:",
                        "data:",
                        "https://maps.gstatic.com",
                        "https://maps.googleapis.com",
                    ],
                    "img-src": [
                        "'self'",
                        "blob:",
                        "data:",
                        "https://maps.gstatic.com",
                        "https://maps.googleapis.com",
                        "khmdb0.google.com",
                        "khmdb0.googleapis.com",
                        "khmdb1.google.com",
                        "khmdb1.googleapis.com",
                        "khm.google.com",
                        "khm.googleapis.com",
                        "khm0.google.com",
                        "khm0.googleapis.com",
                        "khm1.google.com",
                        "khm1.googleapis.com",
                        "khms0.google.com",
                        "khms0.googleapis.com",
                        "khms1.google.com",
                        "khms1.googleapis.com",
                        "khms2.google.com",
                        "khms2.googleapis.com",
                        "khms3.google.com",
                        "khms3.googleapis.com",
                        "streetviewpixels-pa.googleapis.com",
                        "market-assets.strapi.io",
                        "https://tile.openstreetmap.org",
                        "https://a.tile.openstreetmap.org",
                        "https://b.tile.openstreetmap.org",
                        "https://c.tile.openstreetmap.org",
                    ],
                    upgradeInsecureRequests: null,
                },
            },
        },
    },
    "strapi::cors",
    "strapi::poweredBy",
    "strapi::query",
    "strapi::body",
    "strapi::session",
    "strapi::favicon",
    "strapi::public",
];

⚙️ Usage

Adding the location field

• Go to Content-Type Builder → select a content type → Add another field → Custom tab → choose the location field, name it (e.g. coords) and save.

Location data stored

Each location field stores JSON with: lat, lng, address, city, state (province/state), country, and countryCode. Geometry is stored in PostGIS for distance queries.

Filtering by location (geo distance) — $location

Use the $location query parameter to find entries within a distance (meters) of a point.

Format 1 — comma-separated (lat,lng,range):

GET /api/restaurants?$location[coords]=49.200949303006055,16.623833585841673,5000

Returns restaurants within 5000 m of the given coordinates. The range (5000) is optional.

Format 2 — object with lat, lng, range:

GET /api/restaurants?$location[coords][lat]=49.200949303006055&$location[coords][lng]=16.623833585841673&$location[coords][range]=5000

Optional: restrict by state/province

Add state to limit results to a given state (or province):

GET /api/restaurants?$location[coords][lat]=37.7&$location[coords][lng]=-122.4&$location[coords][range]=50000&$location[coords][state]=California

Replace restaurants and coords with your collection and location field names.

Filtering by address (city, state, country, etc.) — $address

Use the $address query parameter to filter by address fields (partial match, case-insensitive).

Examples for a content type Restaurant with location field coords:

• By city:
  GET /api/restaurants?$address[coords][city]=amsterdam

• By state/province:
  GET /api/restaurants?$address[coords][state]=California

• By country:
  GET /api/restaurants?$address[coords][country]=netherlands

• By country code (exact):
  GET /api/restaurants?$address[coords][countryCode]=US

• By address text:
  GET /api/restaurants?$address[coords][address]=Main Street

Chaining filters (all conditions are AND):

GET /api/restaurants?$address[coords][city]=amsterdam&$address[coords][country]=netherlands
GET /api/restaurants?$address[coords][state]=California&$address[coords][countryCode]=US

Replace restaurants and coords with your collection and location field names.