Source: https://developers.woosmap.com/get-started/

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

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

# Get Started



Get up and running with Woosmap in 5 minutes. This guide walks you through account setup and your first API call.

## 1. Create Your Account

1. Go to [woosmap.com/sign\_up](https://www.woosmap.com/en/sign_up/?utm_campaign=Woosmap%20Sign-up&utm_source=Developers-documentation) and create your account.
2. Check your email and click the activation link.
3. Log in to the [Woosmap Console](https://console.woosmap.com).

## 2. Create an Organization

After logging in, you’ll be prompted to create an **organization**. This is your team workspace where you can:

- Invite team members
- Manage multiple projects
- View usage analytics

## 3. Create a Project

A project contains your API keys and settings. When creating a project:

1. **Name your project** (e.g., “My Store Locator”)
2. **Add your domains** — the websites allowed to use your API keys (e.g., `localhost`, `mysite.com`)
3. **Enable the APIs** you need

Only enable the APIs you actually use. You can always add more later.

## 4. Get Your API Keys

Woosmap uses two types of API keys:

| Key Type | Use For | How to Get |
| --- | --- | --- |
| **Public Key** | Client-side (websites, browsers) | Auto-generated when you create a project |
| **Private Key** | Server-side or mobile apps | Manually created in the Security tab |

### Public API Key

A **Public API Key** is automatically created when you create a project. Find it in the Console under **Project → Security → Project API key(s)**.

You must add authorized domains before your Public Key works. Add your domains (e.g., `localhost`, `*.mysite.com`) in the **Domains** section. Don’t include `http://` or `https://`.

You must specify which APIs to enable for your project among the following:

- [Stores API](https://developers.woosmap.com/products/stores-api/overview/)
- [Localities API](https://developers.woosmap.com/products/localities/overview/)
- [Address API](https://developers.woosmap.com/products/address-api/get-started/)
- [Distance API](https://developers.woosmap.com/products/distance-api/overview/)
- [Geolocation API](https://developers.woosmap.com/products/geolocation-api/location/)
- [Map API](https://developers.woosmap.com/products/map-api/get-started/)

### Private API Key (Optional)

If you need server-side or mobile access, create a **Private API Key** :

1. Go to **Project → Security**
2. Click **Add a Private Key**
3. Name your key and set permissions (read-only or read/write)
4. Add restrictions (IP addresses for servers, Bundle ID for iOS, Package ID for Android)

Always restrict your Private Keys. Unrestricted keys are a security risk.

- [Learn more about API key security →](/api-reference/authentication/)

## 5. Make Your First API Call

Let’s test your setup with the Localities API. Replace `YOUR_PUBLIC_API_KEY` with your actual key:

```javascript
const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
```

```shell
curl -L 'https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'
```

```python
import requests

url = "https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY"

payload = {}
headers = {
    'Referer': 'http://localhost'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```

```text
https://api.woosmap.com/localities/autocomplete/
  ?components=country%3Agb
  &input=Lond
  &no_deprecated_fields=true
  &key=YOUR_PUBLIC_API_KEY
```

```javascript
const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY',
  headers: { 
    'Referer': 'http://localhost'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});
```

```java
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY")
  .method("GET", body)
  .addHeader("Referer", "http://localhost")
  .build();
Response response = client.newCall(request).execute();
```

```ruby
require "uri"
require "net/http"

url = URI("https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY")

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

request = Net::HTTP::Get.new(url)
request["Referer"] = "http://localhost"

response = https.request(request)
puts response.read_body
```

A successful response returns location suggestions:

```json
{
  "localities": [
    {
      "description": "London, England, United Kingdom",
      "matched_substrings": [...],
      "public_id": "..."
    }
  ]
}
```

## What’s Next?

Choose your path based on what you want to build:

| I want to… | Start here |
| --- | --- |
| Add address autocomplete to a form | [Localities API →](/products/localities/overview/) |
| Show a map with my store locations | [Map JS API →](/products/map-api/get-started/) |
| Calculate distances or routes | [Distance API →](/products/distance-api/overview/) |
| Build a complete store locator | [Store Locator Widget →](/products/widgets/store-locator-widget/quick-start/) |
| Track user location in a mobile app | [Geofencing SDK →](/products/geofencing-sdk/get-started/) |

- [Explore all Woosmap products →](/)
- [Need help? Contact us →](/support/contact/)