> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loqate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Store Finder Quick Start Guide

> Find and display your nearest store locations with distance calculations and interactive maps

**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

* [**Create List**](/api-reference/store-finder/location-management-create-list) - Create a list of store locations
* [**Update List or Point**](/api-reference/store-finder/location-management-update-list-or-point) - Update existing lists or individual points
* [**Delete List or Point**](/api-reference/store-finder/location-management-delete-list-or-point) - Remove lists or individual points
* [**Get List**](/api-reference/store-finder/location-management-get-list) - Retrieve location list details

### Geocoding & Distance

* [**Geocoding Typeahead**](/api-reference/store-finder/geocoding-typeahead) - Search for towns, cities, states, and postcodes
* [**Global Geocoding**](/api-reference/store-finder/global-geocoding) - Convert addresses to coordinates
* [**Global Distance Finder**](/api-reference/store-finder/global-distance-finder) - Calculate road-based distances and travel times
* [**Mapping**](/api-reference/store-finder/mapping) - Generate signed URLs for map tile rendering

## Getting Started

1. [Create an API key](/loqate-basics/create-an-api-key) if you don't have one
2. Create a Store Finder service in your [account](https://account.loqate.com/account#/Setup/) (generates Service and Management keys, see more in the [FAQ](/our-services/store-finder/store-finder-quick-start#faq) about these keys)
3. Create a Location List with your stores ([via account UI](https://account.loqate.com/account#/Setup/) or [Create List API](/api-reference/store-finder/location-management-create-list))
4. Make your first request to find nearest stores

Here's a minimal working example:

<CodeGroup>
  ```shell cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.10/json6.ws"

  payload = {
      "Key": "YOUR_API_KEY",
      "LocationListId": "YOUR_LIST_ID",
      "OriginLocation": {
          "Latitude": "51.5074",
          "Longitude": "-0.1278"
      },
      "MaxDistance": 50000,
      "MaxResults": 10
  }

  response = requests.post(url, json=payload)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = 'https://api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.10/json6.ws';

  const payload = {
    Key: 'YOUR_API_KEY',
    LocationListId: 'YOUR_LIST_ID',
    OriginLocation: {
      Latitude: '51.5074',
      Longitude: '-0.1278'
    },
    MaxDistance: 50000,
    MaxResults: 10
  };

  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });

  const data = await response.json();
  console.log(data);
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  $payload = json_encode([
    "Key" => "YOUR_API_KEY",
    "LocationListId" => "YOUR_LIST_ID",
    "OriginLocation" => [
      "Latitude" => "51.5074",
      "Longitude" => "-0.1278"
    ],
    "MaxDistance" => 50000,
    "MaxResults" => 10
  ]);

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.10/json6.ws",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  ]);

  $response = curl_exec($curl);
  curl_close($curl);

  echo $response;
  ```

  ```go Go theme={null}
  package main

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"io"
  )

  func main() {
  	url := "https://api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.10/json6.ws"

  	payload := map[string]interface{}{
  		"Key":            "YOUR_API_KEY",
  		"LocationListId": "YOUR_LIST_ID",
  		"OriginLocation": map[string]string{
  			"Latitude":  "51.5074",
  			"Longitude": "-0.1278",
  		},
  		"MaxDistance": 50000,
  		"MaxResults":  10,
  	}

  	jsonPayload, _ := json.Marshal(payload)
  	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
  	req.Header.Add("Content-Type", "application/json")

  	res, _ := http.DefaultClient.Do(req)
  	defer res.Body.Close()
  	body, _ := io.ReadAll(res.Body)

  	fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.10/json6.ws")
    .header("Content-Type", "application/json")
    .body("{\"Key\":\"YOUR_API_KEY\",\"LocationListId\":\"YOUR_LIST_ID\",\"OriginLocation\":{\"Latitude\":\"51.5074\",\"Longitude\":\"-0.1278\"},\"MaxDistance\":50000,\"MaxResults\":10}")
    .asString();
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'json'

  url = URI("https://api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.10/json6.ws")

  payload = {
    Key: "YOUR_API_KEY",
    LocationListId: "YOUR_LIST_ID",
    OriginLocation: {
      Latitude: "51.5074",
      Longitude: "-0.1278"
    },
    MaxDistance: 50000,
    MaxResults: 10
  }

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(url)
  request["Content-Type"] = "application/json"
  request.body = payload.to_json

  response = http.request(request)
  puts response.read_body
  ```
</CodeGroup>

## Response

You'll receive a list of stores sorted by distance:

```json theme={null}
{
  "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.

<Accordion title="Complete Response Structure">
  The full response includes additional fields:

  ```json theme={null}
  {
    "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

  | Field                           | Type    | Description                              |
  | ------------------------------- | ------- | ---------------------------------------- |
  | `DestinationLocation.Id`        | string  | Store identifier from your Location List |
  | `DestinationLocation.Name`      | string  | Store name                               |
  | `DestinationLocation.Address`   | string  | Store address                            |
  | `DestinationLocation.Latitude`  | string  | Store latitude                           |
  | `DestinationLocation.Longitude` | string  | Store longitude                          |
  | `Distance`                      | string  | Road-based distance in kilometers        |
  | `DistanceMiles`                 | string  | Road-based distance in miles             |
  | `DistanceMeters`                | integer | Road-based distance in meters            |
  | `Time`                          | string  | Travel time (human-readable)             |
  | `TimeSeconds`                   | integer | Travel time in seconds                   |
</Accordion>

## Try Store Finder

Test Store Finder using the [Global Distance Finder API reference](/api-reference/store-finder/global-distance-finder?playground=open) to make your first request.

## FAQ

<AccordionGroup>
  <Accordion title="How do I create a Location List?">
    **Via Account UI:**

    1. Go to [Add Service](https://account.loqate.com/account#/Setup/) → **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](/api-reference/store-finder/location-management-create-list) for programmatic management.

    **Managing:**

    * Edit/delete locations in the Locations tab
    * Download as CSV for bulk updates
    * Find lists in [Your Services](https://account.loqate.com/account#/Dashboard/)
  </Accordion>

  <Accordion title="What are Service and Management keys?">
    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](https://account.loqate.com/account#/Setup/).
  </Accordion>

  <Accordion title="Can I test without uploading a Location List?">
    Yes. Pass an array of stores directly in the `Locations` field instead of using `LocationListId`:

    ```json theme={null}
    {
      "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
    }
    ```
  </Accordion>

  <Accordion title="How do I get customer coordinates?">
    Use the [Global Geocoding API](/api-reference/store-finder/global-geocoding) to convert addresses to coordinates:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="Why use road-based distances?">
    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.
  </Accordion>

  <Accordion title="What are the performance limits?">
    * **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.
  </Accordion>

  <Accordion title="How do I display results on a map?">
    Use the [Mapping API](/api-reference/store-finder/mapping) 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.
  </Accordion>

  <Accordion title="Does Store Finder work internationally?">
    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.
  </Accordion>
</AccordionGroup>

## Next Steps

* [Global Distance Finder API](/api-reference/store-finder/global-distance-finder) - Full API reference
* [API Security](/loqate-basics/api-security) - Secure your integration
* [Monitoring Usage](/loqate-basics/monitoring-account-usage) - Track consumption