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.

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.

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:

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:

  • 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

‹ Overview Autocomplete ›
Was this helpful?