Source: https://developers.woosmap.com/api-reference/

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

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

# Woosmap API Reference



The Woosmap Platform API provides a comprehensive set of RESTful endpoints to help you build location-based applications
and services. This documentation is your guide to integrating Woosmap's powerful geospatial capabilities into your
applications.

## Make Your First API Call

To get started, try the Search API to find stores near a location. Replace `YOUR_PRIVATE_API_KEY` with your actual
private key:

**Search for Stores**

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

A successful response returns nearby locations:

```json
{
  "features": [
    {
      "type": "Feature",
      "properties": {
        "store_id": "store_123",
        "name": "Central London Store",
        "address": {
          "lines": ["123 High Street"],
          "city": "London",
          "zipcode": "W1A 1AA"
        },
        "distance": 245
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-0.1278, 51.5074]
      }
    }
  ]
}
```

Once you're ready, explore the sidebar to discover all available endpoints across different API groups.

## Core Concepts

Get familiar with the essential concepts of the Woosmap Platform API.

### Authentication

All Woosmap APIs require authentication using API keys. Learn how to obtain, configure, and secure your API keys.

[→ Authentication Guide](/api-reference/authentication/)

### Rate Limiting

Each API endpoint has specific rate limits to ensure platform stability. Rate limits are documented on individual
endpoint pages and typically range from 1-50 requests per second depending on the endpoint.

### Error Handling

The Woosmap API uses standard HTTP status codes:

- `200` - Success
- `400` - Bad Request (invalid parameters)
- `401` - Unauthorized (invalid or missing API key)
- `403` - Forbidden (API not enabled for your project)
- `429` - Too Many Requests (rate limit exceeded)
- `500` - Internal Server Error

Error responses include a message explaining the issue:

```json
{
  "status": "error",
  "value": "The request is invalid, the data is not a valid JSON."
}
```

## Getting Help

- **Documentation**: Comprehensive guides at [developers.woosmap.com](/get-started/)
- **Community**: Join discussions and share solutions at [forum.woosmap.com](https://forum.woosmap.com/)
- **Support**: Contact us at [support@woosmap.com](mailto:support@woosmap.com)

## Best Practices

**Cache Responses** - Store API responses locally when possible to reduce API calls and improve performance.

**Validate Input** - Check user input before making API calls to prevent unnecessary requests and errors.

**Handle Errors Gracefully** - Implement retry logic with exponential backoff for transient failures.

**Secure Your Keys** - Never expose private API keys in client-side code. Use public keys for browser applications and
private keys only on secure servers.

**Monitor Usage** - Track your API consumption in the [Woosmap Console](https://console.woosmap.com/) to stay within
rate limits and optimize costs.