Source: https://developers.woosmap.com/products/localities/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 REST API Call



Let's make your first API call. We'll search for an address and get its complete details—the basic workflow you'll use
in almost every implementation.

## What You Need

You'll need a **private API key** for server-side requests. If you're new to Woosmap, start with
the [Get Started](/get-started/) page to create your account and project. Learn more
about [API Keys and restrictions](/api-reference/authentication/) to understand how to secure them properly. Don't expose your
private key in client-side code or commit it to version control.

You'll also need [cURL](https://curl.se/) or any HTTP client (Postman, Insomnia, etc.). The examples below use cURL
since it's popular and available on most systems.

## Step 1: Search for an Address

First, get suggestions based on what a user might type. Try searching for "10 downing street":

```bash
curl "https://api.woosmap.com/localities/autocomplete/?input=10+downing+street&private_key=YOUR_PRIVATE_API_KEY&types=address&no_deprecated_fields=true"
```

Replace `YOUR_PRIVATE_API_KEY` with your actual key.

### Understanding the Response

You'll receive a JSON response containing an array called `localities`. Each object in the array represents a single
location suggestion.

Notice the two most important fields for each suggestion:

- `description`: A human-readable text of the suggested address.
- `public_id`: A unique identifier for that specific location.

Here's a simplified example of the response:

```json
{
  "localities": [
    {
      "description": "10 Downing Street, London, SW1A 2AA, United Kingdom",
      "public_id": "aGVyZTphZjpzdHJlZXRzZWN0aW9uOlpWN1...IzNQQ"
    }
  ]
}
```

That `public_id` is what you need for the next step.

## Step 2: Get Complete Address Details

Copy the `public_id` from the response above and use it to fetch the full address information:

```bash
curl "https://api.woosmap.com/localities/details/?public_id=PASTE_THE_PUBLIC_ID_HERE&private_key=YOUR_PRIVATE_API_KEY"
```

Now you get the complete picture:

```json
{
  "result": {
    "public_id": "aGVyZTphZjpzdHJlZXRzZWN0aW9uOlpWN1NSWDhMUlNlRVpWU3hQMUhFREQ6Q2dnSUJDRHd5c25UQWhBQkdnSXhNQQ==",
    "types": ["address"],
    "formatted_address": "10 Downing Street, London, SW1A 2AA, United Kingdom",
    "geometry": {
      "location": {
        "lat": 51.50336,
        "lng": -0.12767
      },
      "accuracy": "ROOFTOP"
    },
    "address_components": [
      {
        "types": ["country", "administrative_area_level_0"],
        "long_name": "United Kingdom",
        "short_name": "GB"
      },
      {
        "types": ["state"],
        "long_name": "England",
        "short_name": "England"
      },
      {
        "types": ["county"],
        "long_name": "London",
        "short_name": "LDN"
      },
      {
        "types": ["district"],
        "long_name": "Westminster",
        "short_name": "Westminster"
      },
      {
        "types": ["locality"],
        "long_name": "London",
        "short_name": "London"
      },
      {
        "types": ["postal_codes"],
        "long_name": "SW1A 2AA",
        "short_name": "SW1A 2AA"
      },
      {
        "types": ["route"],
        "long_name": "Downing Street",
        "short_name": "Downing Street"
      },
      {
        "types": ["street_number"],
        "long_name": "10",
        "short_name": "10"
      }
    ]
  }
}
```

The response gives you everything you need:

- `formatted_address` - Ready to display or store
- `geometry.location` - Coordinates for mapping
- `address_components` - Structured data (street number, city, postal code, etc.) you can parse however you need

## Next Steps

Now that you've completed the basic workflow (Autocomplete → Details), explore these resources:

## What's Next

- Check the [Localities Autocomplete Feature](/products/localities/features/autocomplete/) to see all the parameters you can
  use to filter and customize results
- Read the [Integration Path Guide](/products/localities/guides/integration-path/) to choose the best approach for your
  project (REST API, JS SDK, Widget, etc.)
- Browse the [Tuning Guide](/products/localities/guides/tuning-localities-results/) to learn how to optimize search
  results for your use case