# Search API

Last updated:

<!-- -->

October 18, 2026

<!-- -->

\| 8 minutes read

<br />

<br />

[v](/docs/cloud-rest-api/guides/locations-search/CHANGELOG/)

<!-- -->

[1.0.2 Release notes →](/docs/cloud-rest-api/guides/locations-search/CHANGELOG/)

<br />

<br />

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 is 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 one of 25 predefined meta categories such as `gas_stations`, `food&drink`, or `accommodation`. 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.

:::info Complete API Reference View the complete [Search API Reference](/docs/cloud-rest-api/api/search-api.html) for detailed request/response schemas, examples, and interactive documentation. :::

***

**Endpoint:** `POST /locate`

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

### Key Features[​](#key-features "Direct link to 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[​](#required-parameters "Direct link to Required Parameters")

At least one of `text` or geographic filter recommended (`at`, `in`, `along`)

### Optional Parameters[​](#optional-parameters "Direct link to Optional Parameters")

* `text` - Search query text (place name, address, keyword)

* `categories` - Array of POI meta category filters (e.g., `["gas_stations", "food&drink"]`)

* `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: 15)

* `locale` - ISO 639-2 / ISO 639-3 language code for the result (default: `"en"`)

* `target` - Restrict search to one or more result types:

  <!-- -->

  * `pois` - Search in map POIs
  * `addresses` - Search in map addresses
  * `cities` - Search in map cities

* `exact` - Exact match on text tokens, no partial matches (default: `false`)

* `fuzzy` - Enable text token autocorrection when no results are found (default: `true`)

* `debug` - If `true`, the result is beautified for easy human read (default: `false`)

### Example Request - Find Gas Stations Along Route[​](#example-request---find-gas-stations-along-route "Direct link to Example Request - Find Gas Stations Along Route")

```bash
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@IaAK}@YwDKkAMoAUwDG{AGgBGeD@m@Ba@n@}FH}@Bs@@y@@{@KmDGmBMyBI}@",
      "radius": 5000
    },
    "limit": 10
  }'

```

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

### Example Request - Search Restaurants in Area[​](#example-request---search-restaurants-in-area "Direct link to Example Request - Search Restaurants in Area")

```bash
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": ["food&drink"],
    "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[​](#example-request---find-address-around-point "Direct link to Example Request - Find Address Around Point")

```bash
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[​](#response-structure "Direct link to Response Structure")

The API returns a JSON array of objects, each containing:

* `info` - Copyright and attribution information

* `results` - Array of place objects, each containing:

  <!-- -->

  * `coordinates` - Location as `[longitude, latitude]`

  * `entrance` - Entrance coordinates as `[longitude, latitude]` (when available)

  * `name` - Place name

  * `native_name` - Place name in native language

  * `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

  * `distance` - Distance from search point in meters (when applicable)

## POI Categories[​](#poi-categories "Direct link to POI Categories")

The Search API supports the following categories for filtering results. Pass one or more values in the `categories` array.

**Fuel Stations**

`gas_stations` · `petrol_station`

**Parking**

`park_and_ride` · `parking` · `parking_garage` · `parking_lot` · `parking_meter` · `rv_park` · `truck_parking` · `truck_stop`

**Food & Drink**

`bakery` · `bar` · `coffee_shop` · `drinking_water` · `fast_food` · `food&drink` · `restaurant` · `specialty_food_store` · `tea_house` · `wine_and_spirits` · `winery`

**Accommodation**

`accommodation` · `alpine_hut` · `booking.com_hotel` · `camping` · `chalet` · `hotel`

**Medical Services**

`dentist` · `emergency_service` · `health_care_service` · `hospital` · `medical_service` · `medical_services` · `optician` · `pharmacy` · `physician` · `retirement_home` · `veterinarian`

**Shopping**

`agriculture` · `automobile_dealership` · `bicycle_shop` · `bicycle_tube_vending_machine` · `bookstore` · `butcher` · `cigarettes_vending_machine` · `clothing_store` · `coffee_vending_machine` · `convenience_store` · `department_store` · `discount_store` · `do_it_yourself` · `drinks_vending_machine` · `electronics_store` · `entertainment_electronics` · `floor_coverings_and_carpets` · `flowers` · `food_vending_machine` · `furniture` · `garden_centre` · `gift_shop` · `glass_and_windows` · `grocery` · `hairdresser` · `hardware_store` · `home_improvement` · `home_improvement_centre` · `home_specialty_store` · `jewellery` · `lottery_shop` · `major_appliance` · `men's_apparel` · `motorcycle_dealership` · `music` · `newspaper_vending_machine` · `office_supply_store` · `other_general_merchandise` · `paint_shop` · `photography` · `shoe_store` · `shopping` · `specialty_clothing_store` · `specialty_store` · `sporting_goods_store` · `variety_store` · `vending_machine` · `women's_apparel`

**Car Services**

`auto_dealership_-_used_cars` · `auto_parts` · `auto_service` · `automobile_club` · `car_services` · `car_sharing` · `car_wash` · `rental_car_agency`

**Public Transport**

`airport` · `bicycle_rental` · `bus_station` · `commuter_train_station` · `ferry_terminal` · `helipad` · `local_transit` · `marina` · `public_transit_stop` · `public_transit_tickets_kiosk` · `public_transport` · `ski_lift` · `subway_entrance` · `subway_station` · `taxi_stand` · `train_station` · `tram_station` · `transportation_service`

**Wikipedia**

`wiki` · `wikipedia`

**Education**

`education` · `higher_education` · `library` · `school` · `science_and_research_institute`

**Entertainment**

`amusement_park` · `animal_park` · `banquet_hall` · `casino` · `cinema` · `cocktail_lounge` · `entertainment` · `night_club` · `nightlife` · `performing_arts` · `video_rental`

**Public Services**

`animal_waste_bags_dispenser` · `child_care_centre` · `city_hall` · `civic_centre` · `convention_centre` · `county_council` · `court_house` · `embassy` · `fire_station` · `government_office` · `military_base` · `parcel_locker` · `police_service` · `police_station` · `post_office` · `public_services` · `public_toilets` · `recycling` · `social_service` · `waste_and_sanitary`

**Geographical Area**

`archaeological_site` · `border_crossing` · `cave` · `forest` · `geographic_area` · `island` · `national_park` · `peak` · `playground` · `recreation_area` · `water`

**Business**

`atm` · `attorney` · `bank` · `bicycle_service` · `boats` · `business` · `business_facility` · `business_services` · `cheque_cashing_service` · `communication` · `computers_and_software` · `currency_exchange` · `dry_cleaning_and_laundry` · `funeral_director` · `industrial` · `money_transferring_service` · `mover` · `real_estate_agency` · `repair_service` · `route_66` · `storage` · `tailor_shop` · `tax_services` · `telecom` · `timber` · `toll_station` · `travel_agent` · `weigh_station`

**Sightseeing**

`historical_monument` · `lighthouse` · `museum` · `sightseeing` · `tourist_attraction` · `tourist_information` · `viewpoint` · `windmill`

**Religious Places**

`cemetery` · `church` · `mosque` · `place_of_worship` · `religious_places` · `synagogue` · `temple`

**Roadside**

`bicycle_traffic_light` · `give_way_sign` · `highway_exit` · `pedestrian_crossing` · `pedestrian_traffic_light` · `race_track` · `rest_area` · `road_assistance` · `roadside` · `shelter` · `stop_sign` · `traffic_calming` · `traffic_light`

**Sports**

`bowling_centre` · `golf_course` · `golf_practice_range` · `health_club` · `ice_skating` · `recreation` · `ski_resort` · `sporting_and_instructional_camp` · `sports` · `sports_activities` · `sports_centre` · `sports_complex` · `swimming_pool`

**Uncategorized**

`loading_dock` · `rope` · `tree` · `uncategorized`

**Hydrants**

`fire_hydrant` · `hydrants` · `pillar_hydrant` · `pipe_hydrant` · `pond_hydrant` · `sump_buster` · `underground_hydrant` · `wall_hydrant` · `water_tank_hydrant`

**Emergency Services Support**

`ambulance_station` · `defibrillator` · `emergency_landing_site` · `emergency_phone` · `emergency_services_support` · `emergency_ward_entrance` · `emergency_ward_entrance_-_rescue_service` · `emergency_ward_entrance_-_walk_in` · `first_aid_kit`

**Civil Emergency Infrastructure**

`air_raid_siren` · `civil_defense_siren` · `civil_emergency_infrastructure` · `emergency_access_point` · `emergency_assembly_point` · `emergency_assembly_point_-_earthquake` · `emergency_assembly_point_-_fire` · `emergency_assembly_point_-_flood` · `emergency_assembly_point_-_landslide` · `emergency_assembly_point_-_tornado` · `emergency_assembly_point_-_tsunami` · `fire_siren` · `siren` · `tornado_siren` · `tsunami_siren`

**Charging Stations**

`charging_station` · `charging_stations`

**Bicycle Charging Stations**

`bicycle_charging_station` · `bike_charging_stations`

**Bicycle Parking**

`bicycle_parking` · `bike_parking`

**Other**

`advertising` · `block` · `bollard` · `bus_trap` · `chain` · `gate` · `hamlet` · `lift_gate` · `named_place` · `neighborhood` · `power_tower` · `public_sport_airport` · `residential_area` · `slipway` · `utilities` · `water_tower`

## Related Documentation[​](#related-documentation "Direct link to Related Documentation")

For information about routing between locations you've discovered with the Search API, see [Routing API](/docs/cloud-rest-api/guides/routing-navigation/routing-api.md).

For calculating reachable areas from a searched location, see [Isochrones API](/docs/cloud-rest-api/guides/routing-navigation/isochrones-api.md).

For information about common parameters, see [Common Parameters](/docs/cloud-rest-api/guides/routing-navigation/common-parameters.md).
