Source: https://developers.woosmap.com/products/stores-api/tutorials/making-first-request/

> For clean Markdown of any page, append `.md` to the page URL.

> For a complete documentation index, see https://developers.woosmap.com/llms.txt

# Quickstart: Your First Stores API Call



Let's make your first API call. We'll search for stores near a location, the basic workflow you'll use in almost every
implementation.

## Set Up Demo Data

The fastest way to get started is to create a demo project directly in the Woosmap Console. **No data file needed**.

1. Log in to the [Woosmap Console](https://console.woosmap.com)
2. Navigate to **Use Cases & Products** in the left sidebar
3. Select the **Store Locator** from the Use Cases options
4. Click the **Create demo project** button

This sets up a new project preloaded with Store locations, giving you real data to query right away.

If the **Create demo project** button is not visible, you may have already created a demo. Look for the existing demo project in your workspace.

![Stores Demo in Woosmap Console](/assets/images/stores/console-stores-usecase.png){: .center}

You can use the console to explore the created stores and view them on the map by navigating to the demo project.

## What You Need

Your API key must belong to the demo project you just created — that's where the store data lives. For this tutorial
we'll use a [private key](/api-reference/authentication/#what-is-a-woosmap-private-api-key-restriction).
Create the key in the demo project from the previous step.

You'll also need [cURL](https://curl.se/) or any HTTP client (Postman, Insomnia, etc.).

## Step 1: Search for Stores

Now we have stores in our demo project, and an API key, let's make our first request.

Make a basic search request to retrieve your stores as [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946):

```bash
curl 'https://api.woosmap.com/stores/search/?private_key=YOUR_PRIVATE_API_KEY'
```

Replace `YOUR_PRIVATE_API_KEY` with your actual key.

The result will be paginated as the demo data is quite large. Use `page` and `stores_by_page` query parameters to navigate
results (default is **100**, max is **300**).

## Step 2: Filter by Location

Narrow results to stores near a specific location by adding `lat`, `lng`, and `radius` parameters. Since the sample
dataset contains stores all over the world, let’s focus on London:

```bash
curl 'https://api.woosmap.com/stores/search/?private_key=YOUR_PRIVATE_API_KEY&lat=51.5074&lng=-0.1278&radius=5000'
```

This returns stores within 5 km of central London.

## Step 3: Search by Attributes

Use the `query` parameter to filter stores by their properties.

```bash
curl 'https://api.woosmap.com/stores/search/?private_key=YOUR_PRIVATE_API_KEY&query=type:brand_reseller'
```

This returns stores of the type `brand_reseller`.

## Step 4: Combine Filters

You can combine location and attribute filters in a single request. Use `AND` to chain multiple query conditions together:

```bash
curl 'https://api.woosmap.com/stores/search/?private_key=YOUR_PRIVATE_API_KEY&lat=48.8566&lng=2.3522&radius=5000&query=type:brand_reseller+AND+tag:schedule_a_demo'
```

This returns `brand_reseller` stores tagged with `schedule_a_demo` within 5 km of central Paris. For the full query
syntax including `OR` and `NOT` operators, see [Query Syntax](/products/stores-api/concepts/query-syntax/) and the
[Search Endpoint](/products/stores-api/features/search/) reference.

## What's Next

Now you have an idea of how the Stores API works, how can you integrate it into your project?

- Read the [Integration Path Guide](/products/stores-api/guides/integration-path/) to choose the best approach for your project
- Try [Autocomplete Search](/products/stores-api/features/autocomplete/) for full-text search on localized names

Or try these interactive code examples:

- [CodeSandbox Demo](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/stores-overlay-query/app)
- [JSFiddle Example](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/stores-overlay-query/jsfiddle)
- [GitHub Samples](https://github.com/Woosmap/js-samples/tree/sample/stores-search)
- [React Native - @woosmap/react-native-woosmap](/products/mobile/react-native/store-overlay/)
- [Flutter - woosmap_flutter](/products/mobile/flutter/store-overlay/)