Community Forum

Quickstart: Your First REST API Call

A 5-minute guide to making your first server-side request to the Woosmap Localities REST API using cURL for autocomplete and details.
  1. What You Need
  2. Step 1: Search for an Address
  3. Step 2: Get Complete Address Details
  4. That’s It
  5. What’s Next

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 page to create your account and project. Learn more about API Keys and restrictions 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 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”:

Shell
        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.

Step 2: Understand 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:

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:

Shell
        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:

That’s It

You just completed the basic workflow: Autocomplete returns suggestions, Details gives you the full address. This pattern works for address forms, store locators, delivery apps—anywhere users need to find a location.

What’s Next

‹ Overview Autocomplete ›
Was this article helpful?
Have more questions? Submit a request