Nearest Store API Playground
Send a latitude, longitude, and search radius, then get back the closest store locations as JSON—sorted nearest-first. Try it live below, then copy ready-to-run curl and JavaScript snippets for the production endpoint.
Try It Live
These requests hit a sandboxed demo dataset—no API key required. The production endpoint behaves identically once you add your own locations.
Request
Preset locations
POST /api/tools/nearest-demo · demo dataset · no auth
Response
Pick a city or enter coordinates, then run the request to see the JSON response here.
Ready-to-Run Code for the Production Endpoint
These snippets target the real, key-protected API and update automatically with the values you enter above. Drop in your API key and you’re live.
curl -X POST "https://maptera.switchlabs.dev/api/v1/stores/nearest" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"lat": 40.7128,
"lng": -74.006,
"radius": 50
}'const res = await fetch("https://maptera.switchlabs.dev/api/v1/stores/nearest", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
lat: 40.7128,
lng: -74.006,
radius: 50, // miles
}),
});
const { results } = await res.json();
console.log(results); // sorted nearest-firstEndpoint: https://maptera.switchlabs.dev/api/v1/stores/nearest · API install guide · full API docs
A Store Locator API Built for Developers
Maptera’s nearest-store endpoint is the same engine that powers our no-code widgets—now available as a clean REST API you can drop into any product.
Distance-Sorted Results
Every response is sorted nearest-first using the haversine great-circle distance, with exact mileage on each result so you can render “2.4 mi away” without extra math.
CORS-Friendly JSON
Call it from the browser, a mobile app, an edge function, or your backend. Clean JSON in, clean JSON out—no SDK required.
One Source of Truth
The locations behind the API are the same ones rendered in your Maptera widget and SEO location pages. Update once, reflected everywhere.
Coordinates or Geocoded Input
Pass lat/lng directly, or geocode a ZIP or address first with Maptera’s built-in smart geocoding and feed the result into nearest-store.
Key-Protected & Rate-Aware
Production requests authenticate with a bearer API key tied to your account, so your store data stays under your control.
Documented & Predictable
A stable response shape—query, count, and a results array—means you can build against it confidently. See the docs for the full schema.
Understanding the Response
The nearest-store endpoint returns a predictable, flat structure that’s easy to map into a UI or another system.
queryThe lat, lng, and radius you sent, echoed back so you can confirm what was searched.
countThe total number of stores that fell within your radius. Useful for “No locations near you” empty states.
results[]An array of matches sorted nearest-first. Each item carries name, address, city, state, latitude, longitude, and distance_miles.
What a Nearest-Store API Is For
“Find a store near me” is one of the highest-intent actions a shopper can take. A nearest-store API turns a pair of coordinates into a ranked list of your physical locations, so you can power a custom store finder, a checkout “pick up in store” selector, a delivery-zone check, or a “book the closest branch” flow—anywhere you need to connect a person to the right location fast.
While Maptera’s no-code widget handles the common case—embed a map, done—an API gives engineering teams full control. You decide the UI, the framework, and the moment the lookup happens. The endpoint stays boringly simple on purpose: send lat, lng, and an optional radius; receive sorted results. That predictability is what makes it easy to build on.
Common ways teams use it
- Custom store finders: Build a fully branded locator in your own stack while Maptera manages the location data and distance math.
- Checkout & fulfillment: Surface the closest pickup point or assign an order to the nearest location automatically.
- Mobile apps: Use the device’s GPS coordinates to show the nearest branch, dealer, clinic, or pickup locker.
- Routing & logistics: Pre-filter candidate locations by proximity before running heavier routing logic.
From Playground to Production
The playground above runs against a sandbox dataset so you can see the exact response shape before writing a line of code. Moving to production is three steps:
Create an account and add your locations
Sign up free and import your stores via CSV, the dashboard, or the API. Maptera geocodes addresses automatically, so you don’t have to source coordinates yourself.
Generate an API key
Create a key from your dashboard and pass it as a bearer token. Full REST API access is part of the Enterprise plan—see pricing for the full breakdown.
Swap the URL and ship
Point the snippets above at the production endpoint, add your key, and you’re serving live nearest-store results. The API install guide and documentation cover authentication, parameters, and the full response schema.
Prefer No Code?
Not every team needs to build against the API. If you run a Shopify or Wix store—or any website—you can embed a fully featured locator in minutes without writing any code. Explore the Shopify, Wix, and universal embed install options, browse industry solutions, or check out more free tools. Paid plans start at $17.99/month.
Frequently Asked Questions
What does the nearest-store API return?
A JSON payload with your search query echoed back, a total match count, and a results array sorted nearest-first. Each result includes the store name, address, city, state, latitude, longitude, and the great-circle distance in miles from the search point.
How is distance calculated?
Maptera uses the haversine formula to compute the great-circle distance between the search coordinates and each store, then sorts results from closest to farthest. The playground on this page uses the exact same calculation as the production API.
Do I need latitude and longitude, or can I send an address?
The nearest-store endpoint takes coordinates. If you only have a postal address or ZIP code, geocode it first with Maptera’s geocoding endpoint (or any geocoder), then pass the resulting lat/lng here. Smart geocoding is built into every Maptera plan.
How do I get an API key?
Create a free Maptera account, add your store locations, then generate an API key from your dashboard. Full REST API access is included on the Enterprise plan; see the pricing page for details.
Is the API CORS-friendly?
Yes. Responses send permissive CORS headers so you can call the endpoint directly from a browser, a serverless function, a mobile app, or a backend service.
Get your API key in minutes
Create a free account, add your locations, and start hitting the nearest-store endpoint today. No credit card required to get started.
Ready to help customers find your stores?
Get started today with our 14-day free trial. No credit card required.