Skip to main content
Store Finder combines location data with distance calculations and interactive mapping to help customers find your nearest stores with accurate travel times and distances.

​
Coverage

  • Global: Distance calculations and geocoding available worldwide
  • Regional restrictions: Distance calculation supported between countries within the same region (e.g., France to Germany within Europe)

​
Available Endpoints

Store Finder provides 8 API endpoints:

​
Location Management

​
Geocoding & Distance

​
Getting Started

  1. Create an API key if you don’t have one
  2. Create a Store Finder service in your account (generates Service and Management keys, see more in the FAQ about these keys)
  3. Create a Location List with your stores (via account UI or Create List API)
  4. Make your first request to find nearest stores
Here’s a minimal working example: 
curl --request POST \
  --url https://api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.10/json6.ws \
  --header 'Content-Type: application/json' \
  --data '{
    "Key": "YOUR_API_KEY",
    "LocationListId": "YOUR_LIST_ID",
    "OriginLocation": {
      "Latitude": "51.5074",
      "Longitude": "-0.1278"
    },
    "MaxDistance": 50000,
    "MaxResults": 10
  }'

​
Response

You’ll receive a list of stores sorted by distance: 
{
  "DestinationLocations": [
    {
      "DestinationLocation": {
        "Id": "store-002",
        "Name": "Covent Garden Store",
        "Address": "12 King Street, Covent Garden, London, WC2E 8HN",
        "Latitude": "51.5123",
        "Longitude": "-0.1245"
      },
      "Distance": "0.9 km",
      "DistanceMiles": "0.6 miles",
      "DistanceMeters": 900,
      "Time": "4 minutes",
      "TimeSeconds": 240
    },
    {
      "DestinationLocation": {
        "Id": "store-001",
        "Name": "Oxford Street Store",
        "Address": "456 Oxford Street, London, W1C 1AP",
        "Latitude": "51.5155",
        "Longitude": "-0.1426"
      },
      "Distance": "1.8 km",
      "DistanceMiles": "1.1 miles",
      "DistanceMeters": 1800,
      "Time": "8 minutes",
      "TimeSeconds": 480
    }
  ]
}
The response includes:
  • Stores sorted by distance (closest first)
  • Multiple distance formats (km, miles, meters)
  • Travel times calculated from historical traffic data
  • Store details from your Location List
Note: Results are limited to 100 stores within a 500km radius maximum. Road-based distances account for actual routes, not straight lines.
The full response includes additional fields:
{
  "OriginLocation": {
    "Id": "origin",
    "Name": "Customer Location",
    "Address": "123 Main Street, London",
    "Latitude": "51.5074",
    "Longitude": "-0.1278"
  },
  "DestinationLocations": [
    {
      "DestinationLocation": {
        "Id": "store-001",
        "Name": "Oxford Street Store",
        "Description": "Flagship location",
        "Address": "456 Oxford Street, London, W1C 1AP",
        "Latitude": "51.5155",
        "Longitude": "-0.1426",
        "OpeningHours": {
          "Monday": {
            "Open": "09:00",
            "Close": "18:00"
          }
        }
      },
      "Distance": "1.8 km",
      "DistanceMiles": "1.1 miles",
      "DistanceMeters": 1800,
      "Time": "8 minutes",
      "TimeSeconds": 480
    }
  ]
}

​
Key Fields

FieldTypeDescription
DestinationLocation.IdstringStore identifier from your Location List
DestinationLocation.NamestringStore name
DestinationLocation.AddressstringStore address
DestinationLocation.LatitudestringStore latitude
DestinationLocation.LongitudestringStore longitude
DistancestringRoad-based distance in kilometers
DistanceMilesstringRoad-based distance in miles
DistanceMetersintegerRoad-based distance in meters
TimestringTravel time (human-readable)
TimeSecondsintegerTravel time in seconds

​
Try Store Finder

Test Store Finder using the Global Distance Finder API reference to make your first request.

​
FAQ

Via Account UI:
  1. Go to Add Service → Location List
  2. Upload CSV with headers: Name, Description, Address, Latitude, Longitude
  3. Optional: Enable “Geocode Address” to add coordinates (500 location max, charges apply)
  4. Note the generated List ID
Via API: Use the Create List API for programmatic management.Managing:
  • Edit/delete locations in the Locations tab
  • Download as CSV for bulk updates
  • Find lists in Your Services
Store Finder creates two API keys automatically:
  • Service key - For public operations (Geocoding, Distance Finder, Mapping). Safe for client-side use.
  • Management key - For private operations (creating/editing lists). Keep server-side only.
Both are generated when you create a Store Finder service in your account.
Yes. Pass an array of stores directly in the Locations field instead of using LocationListId:
{
  "Key": "YOUR_API_KEY",
  "Locations": [
    {
      "Id": "store-1",
      "Name": "Test Store",
      "Latitude": "51.5155",
      "Longitude": "-0.1426"
    }
  ],
  "OriginLocation": {
    "Latitude": "51.5074",
    "Longitude": "-0.1278"
  },
  "MaxDistance": 50000,
  "MaxResults": 10
}
Use the Global Geocoding API to convert addresses to coordinates:
curl "https://api.addressy.com/LocationServices/Geocoding/Global/v1.00/json4.ws?input=123%20Main%20St,%20London&Key=YOUR_API_KEY"
The geocoded coordinates can then be passed as OriginLocation to Distance Finder.
Road-based distances provide accurate travel information by following actual routes. Straight-line distances ignore geographic features like water or terrain, potentially directing customers to inaccessible locations.Travel times use historical traffic data, helping customers assess if they can reach a store quickly.
  • MaxDistance: Up to 500km radius (default 100km, smaller is faster)
  • MaxResults: Up to 100 stores (default 10, fewer is faster)
  • Best practice: Use regional lists and limit results to improve response times
Distance calculation scales linearly with location count - use the fewest points needed.
Use the Mapping API to get signed URLs for map tiles, then render with:
  • MapLibre (recommended)
  • Leaflet
  • Tangram
Signed URLs are valid for one hour. Map tiles use OpenMapTiles styling and OpenStreetMap data. Attribution is included by default.
Yes. Distance calculations work globally and between countries in the same region (e.g., France to Germany in Europe). Ferry routes are included where data is available.

​
Next Steps