Search API

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.

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

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

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

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

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

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.

Key Features​

Required Parameters​

Optional Parameters​

Example Request - Find Gas Stations Along Route​

Example Request - Search Restaurants in Area​

Example Request - Find Address Around Point​

Response Structure​

POI Categories​

Related Documentation​