The store locator API for developers
Nearby search, geocoding, and full store CRUD over a clean REST API. Authenticate with a Bearer API key, get JSON back, and ship a proximity-aware store finder without standing up your own geospatial stack.
# Find the 5 closest locations to a point, within 25 miles
curl "https://maptera.switchlabs.dev/api/widget/nearby?company=123&lat=40.7128&lng=-74.0060&radius=25" \
-H "Authorization: Bearer mk_live_your_api_key"One request returns the closest locations, each with a distance in miles.
What the store locator API does
Four building blocks cover the entire location lifecycle—from importing addresses to answering "what's near me?" in a single call.
Nearby search
GET /api/widget/nearbyPass a latitude, longitude, and radius and get back the closest active locations, each with a precomputed distance in miles. Perfect for "stores near me" features and proximity-ranked lists.
Address geocoding
POST /api/widget/geocodeTurn a free-form address or ZIP code into latitude/longitude coordinates. Chain it into a nearby search so your users can type a city or postcode instead of sharing GPS.
Stores CRUD
GET / POST / PUT / DELETE /api/v1/storesCreate, read, update, and delete locations programmatically. List endpoints support pagination, search, and filtering by city, state, country, and active status.
Bulk import & sync
POST / PUT /api/v1/stores/bulkPush up to 100 locations in a single request and let Maptera geocode them for you. Keep your CMS, ERP, or franchise database in sync without a script that loops one row at a time.
One header. That's the whole setup.
The public REST API authenticates with a Bearer API key. Create a free account, generate a key in your dashboard, and send it on every request. Keys are scoped to your company, so you only ever see your own locations.
Create an account to get a keycurl "https://maptera.switchlabs.dev/api/v1/stores" \
-H "Authorization: Bearer mk_live_your_api_key"Tip: store the key in an environment variable (for example MAPTERA_API_KEY) and never commit it to source control or ship it in client-side bundles.
Copy-paste code samples
Real requests against the documented endpoints. Swap in your API key and company ID and you're live.
Nearby search request
# Find the 5 closest locations to a point, within 25 miles
curl "https://maptera.switchlabs.dev/api/widget/nearby?company=123&lat=40.7128&lng=-74.0060&radius=25" \
-H "Authorization: Bearer mk_live_your_api_key"JSON response
{
"success": true,
"count": 2,
"stores": [
{
"id": 481,
"name": "Downtown Flagship",
"address": "120 Broadway",
"city": "New York",
"state": "NY",
"latitude": 40.7081,
"longitude": -74.0102,
"phone": "+1-212-555-0142",
"distance": 0.42
},
{
"id": 510,
"name": "Midtown Express",
"address": "650 5th Ave",
"city": "New York",
"state": "NY",
"latitude": 40.7587,
"longitude": -73.9787,
"distance": 3.18
}
]
}Geocode, then search (JavaScript fetch)
// Geocode an address, then find nearby stores — browser or Node 18+
const BASE = 'https://maptera.switchlabs.dev';
const KEY = process.env.MAPTERA_API_KEY; // get one at /register
// 1) Turn a typed address into coordinates
const geo = await fetch(`${BASE}/api/widget/geocode`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ address: '1600 Amphitheatre Pkwy, Mountain View, CA' }),
}).then((r) => r.json());
// 2) Search around those coordinates
const params = new URLSearchParams({
company: '123',
lat: String(geo.latitude),
lng: String(geo.longitude),
radius: '50',
});
const res = await fetch(`${BASE}/api/widget/nearby?${params}`, {
headers: { Authorization: `Bearer ${KEY}` },
});
const { stores } = await res.json();
console.log(stores.map((s) => `${s.name} — ${s.distance} mi`));Create a store
# Create a single location (lat/lng optional — Maptera geocodes for you)
curl -X POST "https://maptera.switchlabs.dev/api/v1/stores" \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Lincoln Park Store",
"address": "1234 N Halsted St",
"city": "Chicago",
"state": "IL",
"zip_code": "60614",
"phone": "+1-312-555-0188",
"categories": "retail,flagship"
}'Bulk import
# Import many locations at once (up to 100 per request)
curl -X POST "https://maptera.switchlabs.dev/api/v1/stores/bulk" \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"geocode": true,
"stores": [
{ "name": "Austin South", "address": "500 S Congress Ave", "city": "Austin", "state": "TX", "zip_code": "78704" },
{ "name": "Austin North", "address": "1100 Burnet Rd", "city": "Austin", "state": "TX", "zip_code": "78758" }
]
}'Endpoint reference
A quick map of the routes you'll reach for most. The full interactive spec, request bodies, and response schemas live in the API documentation.
| Method | Endpoint |
|---|---|
| GET | /api/widget/nearbyFind active stores near a lat/lng, ranked by distance. |
| GET | /api/widget/storesList a company’s stores for a map or directory. |
| POST | /api/widget/geocodeConvert a free-form address into coordinates. |
| GET | /api/v1/storesList stores with pagination, search, and filters. |
| POST | /api/v1/storesCreate a new store location. |
| GET | /api/v1/stores/{id}Retrieve a single store by ID. |
| PUT | /api/v1/stores/{id}Update fields on an existing store. |
| DELETE | /api/v1/stores/{id}Remove a store from your account. |
| POST | /api/v1/stores/bulkCreate up to 100 stores in one call. |
| PUT | /api/v1/stores/bulkUpdate many stores by ID or external_id. |
Built to run in production
Predictable JSON, sensible defaults, and the operational guardrails you expect from an API you put in front of customers.
Rate limits
Requests are rate limited per API key to keep the platform fast for everyone, with higher throughput on paid plans. Build in retry-with-backoff on HTTP 429 and you'll rarely notice the ceiling.
Consistent errors
Every response is JSON. Failures return a stable shape with success: false plus error and message fields, so error handling is a single branch, not a guessing game.
Pagination & filters
List endpoints support page and limit, plus search and filtering by city, state, country, and active status—so you fetch exactly the rows you need.
Full REST API access is included on the Enterprise plan ($59/month). Compare every tier on the pricing page, or start free and upgrade when you need keys.
Why build a store locator on an API instead of a plugin?
No-code embeds are perfect when you want a map on a marketing site in an afternoon. But the moment your locations live in a system of record—an ERP, a franchise management tool, a custom CMS, or a spreadsheet your ops team updates daily—you need that data to flow automatically. A store locator API lets you treat your locations as data, not as something you re-enter by hand. Sync nightly, react to webhooks, and render the results inside your own app with your own design system.
Geospatial search is also one of those problems that looks simple until you build it. Computing great-circle distance, ranking results, handling the antimeridian, geocoding messy user input, and keeping it all fast under load is real engineering. Maptera's nearby endpoint does the distance math for you and returns a sorted list with a distance field on every record, so your front end just renders what it gets back.
A typical integration in three steps
- 1Seed your locations. Push your existing addresses with
POST /api/v1/stores/bulkand let Maptera geocode them. Re-run the bulk update endpoint whenever your source data changes, matching on your ownexternal_id. - 2Turn input into coordinates. When a visitor types a city or ZIP, call
POST /api/widget/geocodeto resolve it to a latitude and longitude—or read coordinates straight from the browser's geolocation API. - 3Answer "what's near me?" Hit
GET /api/widget/nearbywith the coordinates and a radius, then render the distance-ranked results in your UI. That's the whole loop.
Common use cases
- Dealer and retailer locators: power a "find a dealer" page from your product catalog backend.
- Mobile apps: call the nearby endpoint from iOS, Android, or React Native to show the closest locations to a user's GPS position.
- Headless storefronts: fetch store data at build time or on demand and render it inside Next.js, Astro, or your framework of choice.
- Franchise & multi-location sync: keep hundreds of locations current by piping changes from your operations system through the bulk endpoints.
Prefer no code? You can also drop a fully styled locator onto your site with our Shopify, Wix, and universal embed installs, see it live on the interactive demo, or explore the full feature set across industries.
Store locator API questions
How do I authenticate with the store locator API?
The public REST API uses Bearer API keys. Send your key in the Authorization header as "Authorization: Bearer mk_xxx" on every request. You can generate and manage keys from your dashboard after you create a free account at /register. API keys are scoped to your company, so the endpoints only ever return your own locations.
Which endpoint should I use for a "stores near me" feature?
Use GET /api/widget/nearby with lat, lng, and an optional radius (in miles, default 50). The response includes a distance field on each store so you can render a proximity-ranked list without doing the math client-side. If your user types an address instead of sharing GPS, geocode it first with POST /api/widget/geocode and pass the returned coordinates to the nearby endpoint.
Does the API geocode addresses for me?
Yes. When you create or bulk-import stores without latitude and longitude, Maptera geocodes them automatically (set geocode: true on bulk requests). You can also geocode any free-form address or ZIP code on demand with POST /api/widget/geocode, which is handy for turning user search input into map coordinates.
Can I bulk import all of my locations at once?
Yes. POST /api/v1/stores/bulk accepts up to 100 stores per request and geocodes them for you. PUT /api/v1/stores/bulk updates many stores at once, matched by their Maptera id or your own external_id, which makes it easy to sync from an existing system of record.
Are there rate limits?
Yes. Public API keys are rate limited per key to protect platform stability, with higher throughput available on paid plans. Responses follow standard REST conventions, so build in retry-with-backoff on HTTP 429 and check the documented response shape. See the full API documentation at /docs for current limits.
What format does the API return?
Every endpoint returns JSON. Successful responses include a success: true flag, and list endpoints wrap results with pagination metadata. Errors return a consistent shape with success: false plus error and message fields so you can branch on them programmatically.
Do I need to write code to use Maptera?
No. The API is for developers who want full control, but you can also launch a no-code store locator with our Shopify, Wix, or universal embed install — no API key required. Start at /install to add a map to your site in minutes, then reach for the API when you need automation or a custom front end.
Ready to help customers find your stores?
Get started today with our 14-day free trial. No credit card required.