Skip to main content
GuidesAPI ReferenceExamples

Search API

|

Current version: 1.0.0, View Release Notes

The Search API provides comprehensive location search capabilities, enabling you to discover points of interest, addresses, administrative areas, and geographic locations with high accuracy and relevance. This powerful service combines forward geocoding (text-to-coordinates) and reverse geocoding (coordinates-to-address) functionality, making it essential for location-based applications, delivery systems, store locators, and any service requiring precise geographic information.

The API offers flexible search methods with sophisticated geographic filters - search around a specific point, within a defined area (polygon, circle, or bounding box), or along a route path. With support for POI category filtering, you can narrow results to specific business types like restaurants, gas stations, hotels, or any of hundreds of predefined categories. The ranking-based results ensure the most relevant locations appear first, while detailed address information includes street names, postal codes, administrative divisions, and contact details when available.

Whether you're building a store locator that finds the nearest locations, implementing address autocomplete for better user experience, geocoding user-entered addresses for delivery services, or enriching location data with reverse geocoding, the Search API provides the precision and flexibility needed for professional location intelligence applications.

Complete API Reference

View the complete Search API Reference for detailed request/response schemas, examples, and interactive documentation.

Endpoint: POST /locate

Base URL: https://api.magiclane.net/api/v1

Key Features:​

  • Search for places by name, address, or keyword
  • Filter by POI categories (restaurants, hotels, gas stations, etc.)
  • Geographic filtering: around a point, within an area, or along a path
  • Ranked results based on relevance and proximity
  • Detailed address and contact information
  • Support for administrative area searches

Required Parameters:​

None (at least one of text, categories, or geographic filter recommended)

Optional Parameters:​

  • text - Search query text (place name, address, keyword)
  • categories - Array of POI category filters (e.g., ["gas_stations", "restaurants"])
  • at - Search around a point coordinate [longitude, latitude]
  • in - Search within an area (polygon, circle, or bbox)
    • polygon - Polygon area defined by coordinates or polyline
    • circle - Circle area with center [longitude, latitude] and radius in meters
    • bbox - Bounding box with east, west, south, north coordinates
  • along - Search along a path with:
    • polyline - Encoded polyline path
    • coords - Array of coordinates defining the path
    • radius - Search radius around the path in meters
  • limit - Maximum number of results to return (default: 20)
  • locale - ISO 3166-1 language code for results

Example Request - Find Gas Stations Along Route​

curl -X POST https://api.magiclane.net/api/v1/locate \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "aral",
    "categories": ["gas_stations"],
    "along": {
      "polyline": "uvxmHe{yp@UmBcAuIUsCGk@...",
      "radius": 5000
    },
    "limit": 10
  }'

This finds Aral gas stations within 5km of the specified route.

Example Request - Search Restaurants in Area​

curl -X POST https://api.magiclane.net/api/v1/locate \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "italian restaurant",
    "categories": ["restaurants"],
    "in": {
      "circle": {
        "center": [13.388860, 52.517037],
        "radius": 2000
      }
    },
    "limit": 20,
    "locale": "en"
  }'

This searches for Italian restaurants within a 2km radius of the specified location.

Example Request - Find Address Around Point​

curl -X POST https://api.magiclane.net/api/v1/locate \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Brandenburg Gate",
    "at": [13.377704, 52.516275],
    "limit": 5
  }'

This searches for "Brandenburg Gate" near the specified coordinates.

Response Structure​

The API returns a JSON object containing:

  • info - Copyright and attribution information
  • results - Array of place objects, each containing:
    • coordinates - Location as [longitude, latitude]
    • name - Place name
    • description - Place type/category description
    • address - Detailed address components:
      • street name - Street name
      • street number - House/building number
      • postal code - Postal/ZIP code
      • settlement - Settlement/neighborhood
      • city - City name
      • county - County name
      • state - State/province name
      • country - Country name
      • country code - ISO country code
    • contact - Contact information (when available):
      • Phone - Phone numbers array
      • Email - Email addresses array
      • URL - Website URLs array
    • native_name - Place name in local language
    • distance - Distance from search point in meters (when applicable)

POI Categories​

The Search API supports hundreds of POI categories for filtering results. Common categories include:

Food & Dining:

  • restaurants
  • cafes
  • fast_food
  • bars

Accommodation:

  • hotels
  • motels
  • hostels

Transportation:

  • gas_stations
  • charging_stations
  • parking
  • car_rental

Services:

  • banks
  • atms
  • pharmacies
  • hospitals

Shopping:

  • supermarkets
  • shopping_malls
  • convenience_stores

Entertainment:

  • cinemas
  • theaters
  • museums

For a complete list of available categories, refer to the Search API Reference.

For information about routing between locations you've discovered with the Search API, see Routing API.

For calculating reachable areas from a searched location, see Isochrones API.

For information about common parameters, see Common Parameters.

Last updated on