Search

In this guide you will learn how to search for points of interest (POIs) or addresses.

Setup

First, get an API key token, see the Getting Started guide.

Search entry point

URL:	https://search.magiclaneapis.com/v1

Example

These are complete working examples in several different languages, showing how to use the REST API search. You can try them right now.

curl

Linux terminal / Windows command prompt:

curl "https://search.magiclaneapis.com/v1" -X POST -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_TOKEN" -d @payload.json

Linux note - do not use @~/payload.json instead of @/home/user/payload.json because ~ does not resolve due to the @; use only relative path @payload.json or absolute path @/home/user/payload.json

where

payload.json is a text file containing the following:

complete minimal payload.json file - search type, text to search for (query), target list what to search for, in the case of POIs - also specify POI categories with poi_categs, ref_location a reference location in longitude and latitude around which to search; debug true causes resulting json to be pretty printed;

note that, although the target field and the poi_categs field can be omitted - in that case the search looks only for settlements (villages, towns, cities), regions, countries

{
    "text": "rest",
    "target": ["pois", "addresses"],
    "poi_categs": ["food&drink"],
    "ref_location": [4.89352, 52.36597],
    "debug": true
}

complete payload.json file - all default values shown explicitly - this json request is equivalent to, and produces the same output as, the previous json request above;

{
    "type": "free_text",
    "text": "rest",
    "target": ["pois", "addresses"],
    "poi_categs": ["food&drink"],
    "ref_location": [4.89352, 52.36597],
    "max_results": 15,
    "exact_match": false,
    "fuzzy": false,
    "estimate_hno": true,
    "debug": true,
    "locale": "en"
}

python3

complete minimal python search request - search type, text to search for (query), target list what to search for, in the case of POIs - also specify POI categories with poi_categs, ref_location a reference location in longitude and latitude around which to search; debug true causes resulting json to be pretty printed;

note that the debug parameter is omitted, as the json is stored in the response variable, not printed directly, so formatting the json output is done locally by the json.dumps() function instead;

import requests
import json

url = "https://search.magiclaneapis.com/v1"
headers = {"Content-Type": "application/json", "Authorization": "YOUR_API_KEY_TOKEN" }
payload = {
   "text": "rest",
   "target": ["pois", "addresses"],
   "poi_categs": ["food&drink"],
   "ref_location": [4.89352, 52.36597]
}
response = requests.post(url, json=payload, headers=headers)
r = response.json()
print(json.dumps(r, indent=3))

search request with all default values shown explicitly - this json request is equivalent to, and produces the same output as, the previous json request above;

note that in python, True and False are case-sensitive; the json module is part of python, but the requests module may need to be installed (linux terminal: pip install requests)

import requests
import json
url = "https://search.magiclaneapis.com/v1"
headers = {"Content-Type": "application/json", "Authorization": "YOUR_API_KEY_TOKEN" }
payload = {
   "type": "free_text",
   "text": "rest",
   "target": ["pois", "addresses"],
   "poi_categs": ["food&drink"],
   "ref_location": [4.89352, 52.36597],
   "max_results": 15,
   "exact_match": False,
   "fuzzy": False,
   "estimate_hno": True,
   "debug": True,
   "locale": "en"
}
response = requests.post(url, json=payload, headers=headers)
r = response.json()
print(json.dumps(r, indent=3))

C

This C example uses libcurl which can be installed on Linux (debian/ubuntu flavors), for example, like this:

sudo apt install libcurl4-gnutls-dev

Save the following code in a text file named search.c using your favorite text editor, such as vi or geany, without the line numbers, those are only for reference:

complete search request in C with all default values shown explicitly - search type, text to search for (query), target list what to search for, in the case of POIs - also specify POI categories with poi_categs, ref_location a reference location in longitude and latitude around which to search; debug true causes resulting json to be pretty printed;

#include <curl/curl.h>

int main (int argc, char *argv[])
{
   CURL *curl;
   CURLcode res;

   curl_global_init(CURL_GLOBAL_ALL);
   curl = curl_easy_init();
   if (curl == NULL) { return 128; }

   char* jsonObj = "{"
      "\"type\": \"free_text\","
      "\"text\": \"rest\","
      "\"target\": [\"pois\",\"addresses\"],"
      "\"poi_categs\": [\"food&drink\"],"
      "\"ref_location\": [4.89352, 52.36597],"
      "\"max_results\": 15,"
      "\"exact_match\": false,"
      "\"fuzzy\": false,"
      "\"estimate_hno\": true,"
      "\"debug\": true,"
      "\"locale\": \"en\""
   "}";
   struct curl_slist *headers = NULL;
   curl_slist_append(headers, "Content-Type: application/json");
   curl_slist_append(headers, "Authorization: YOUR_API_KEY_TOKEN");

   curl_easy_setopt(curl, CURLOPT_URL, "https://search.magiclaneapis.com/v1");
   curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "PUT");
   curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
   curl_easy_setopt(curl, CURLOPT_POSTFIELDS, jsonObj);

   res = curl_easy_perform(curl);

   curl_easy_cleanup(curl);
   curl_global_cleanup();
   return res;
}

Compile the program - for example, on Linux, at the terminal/command prompt type:

gcc search.c -lcurl -o search

A binary executable named search is created which can be run like this to send the JSON POST request to the REST API endpoint, receive, and print the response:

./search

D

To install D on Linux (debian/ubuntu flavors), at a terminal/command prompt type:

sudo apt install gdc

https://dlang.org/download.html
D can be downloaded for other platforms from this link

complete search request in D with all default values shown explicitly - search type, text to search for (query), target list what to search for, in the case of POIs - also specify POI categories with poi_categs, ref_location a reference location in longitude and latitude around which to search; debug true causes resulting json to be pretty printed;

copy and paste this code in a text file named search.d, without the line numbers - those are for reference:

import std.stdio;
import std.net.curl;
void main()
{
   string payload = '{
      "type": "free_text",
      "text": "rest",
      "target": ["pois", "addresses"],
      "poi_categs": ["food&drink"],
      "ref_location": [4.89352, 52.36597],
      "max_results": 15,
      "exact_match": false,
      "fuzzy": false,
      "estimate_hno": true,
      "debug": true,
      "locale": "en"
   }';
   auto http = HTTP();
   http.addRequestHeader("Content-Type", "application/json");
   http.addRequestHeader("Authorization", "YOUR_API_KEY_TOKEN");
   auto content = post("https://search.magiclaneapis.com/v1", payload, http);
   writeln(content);
}

Compile the program - for example, on Linux, at the terminal/command prompt type:

gdc search.d -o search

A binary executable named search is created which can be run like this to send the JSON POST request to the REST API endpoint, receive, and print the response:

./search

Julia

To install Julia on Linux (debian/ubuntu flavors), at a terminal/command prompt type:

sudo apt install julia

https://julialang.org/downloads/
Julia can be downloaded for other platforms from this link

To start Julia, type:

julia

To install the JSON and HTTP packages, at the Julia prompt type:

import Pkg; Pkg.add("JSON"); Pkg.add("HTTP")

complete search request in Julia with all default values shown explicitly - search type, text to search for (query), target list what to search for, in the case of POIs - also specify POI categories with poi_categs, ref_location a reference location in longitude and latitude around which to search; debug true causes resulting json to be pretty printed;

copy and paste this code at the Julia prompt, without the line numbers - those are for reference:

using JSON, HTTP
req = """{
  "type": "free_text",
  "text": "rest",
  "target": ["pois", "addresses"],
  "poi_categs": ["food&drink"],
  "ref_location": [4.89352, 52.36597],
  "max_results": 15,
  "exact_match": false,
  "fuzzy": false,
  "estimate_hno": true,
  "debug": true,
  "locale": "en"
  }"""
ans = HTTP.request("POST", "https://search.magiclaneapis.com/v1",
  ["Content-Type" => "application/json",
  "Authorization" => "YOUR_API_KEY_TOKEN"], req);
str = String(ans.body);
print(str)

Kotlin

https://www.jetbrains.com/idea/download
The free IntelliJ IDEA Community Edition IDE can be downloaded from this link

Create a new kotlin project in IntelliJ.

In your new kotlin project, browse to src -> main -> kotlin -> Main.kt

Delete all the code in Main.kt and replace it with the kotlin search request code shown below: (without the line numbers - those are only for reference)

complete search request in kotlin with all default values shown explicitly - search type, text to search for (query), target list what to search for, in the case of POIs - also specify POI categories with poi_categs, ref_location a reference location in longitude and latitude around which to search; debug true causes resulting json to be pretty printed;

package kot.search.post

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse

fun main()
{
   val request: String = """
   {
      "type": "free_text",
      "text": "rest",
      "target": ["pois", "addresses"],
      "poi_categs": ["food&drink"],
      "ref_location": [4.89352, 52.36597],
      "max_results": 15,
      "exact_match": false,
      "fuzzy": false,
      "estimate_hno": true,
      "debug": true,
      "locale": "en"
   }"""
   print(request)
   val client = HttpClient.newBuilder().build();
   val postrequest = HttpRequest.newBuilder()
   .uri(URI.create("https://search.magiclaneapis.com/v1"))
   .header("Content-Type", "application/json")
   .header("Authorization", "YOUR_API_KEY_TOKEN")
   .POST(HttpRequest.BodyPublishers.ofString(request))
   .build()
   val response = client.send(postrequest, HttpResponse.BodyHandlers.ofString());
   println(response.statusCode())
   println(response.body())
}

Click the green triangle play button to compile and run the kotlin search request!

If there is a problem compiling because of a missing standard library, go in the menu to File->Project Structure and in the left panel select Modules and then in the right panel select the Dependencies tab and make sure the [x] KotlinJavaRuntime box is checked, then click Apply and OK, and run the example again.

Groovy

https://www.jetbrains.com/idea/download
The free IntelliJ IDEA Community Edition IDE can be downloaded from this link

Create a new groovy project in IntelliJ.

In your new groovy project, browse to src -> Main.groovy

Delete all the code in Main.groovy and replace it with the groovy search request code shown below: (without the line numbers - those are only for reference)

complete search request in groovy with all default values shown explicitly - search type, text to search for (query), target list what to search for, in the case of POIs - also specify POI categories with poi_categs, ref_location a reference location in longitude and latitude around which to search; debug true causes resulting json to be pretty printed;

static void main(String[] args)
{
   def post = new URL("https://search.magiclaneapis.com/v1").openConnection();
   def message = '''
   {
      "type": "free_text",
      "text": "rest",
      "target": ["pois", "addresses"],
      "poi_categs": ["food&drink"],
      "ref_location": [4.89352, 52.36597],
      "max_results": 15,
      "exact_match": false,
      "fuzzy": false,
      "estimate_hno": true,
      "debug": true,
      "locale": "en"
   }
   '''
   post.setRequestMethod("POST")
   post.setDoOutput(true)
   post.setRequestProperty("Content-Type", "application/json")
   post.setRequestProperty("Authorization", "YOUR_API_KEY_TOKEN")
   post.getOutputStream().write(message.getBytes("UTF-8"));
   def postRC = post.getResponseCode();
   println(postRC);
   if (postRC.equals(200)) {
      println(post.getInputStream().getText());
   }
}

Click the green triangle play button to compile and run the groovy search request!

Scala

https://www.jetbrains.com/idea/download
The free IntelliJ IDEA Community Edition IDE can be downloaded from this link

Create a new scala project in IntelliJ.

If Language: Scala is not listed in the create new project dialog, click on + to the right of the listed languages and select Scala to install the plugin, then restart intellij, create a new project and select Language: Scala.

In your new scala project, browse to the build.sbt file and add this line:

libraryDependencies += "org.scalaj" % "scalaj-http_2.13" % "2.4.2"

Note - at the time of this writing, the latest scala version is 2.13; the scalaVersion you see in build.sbt must match the scalaj-http_2.13 version; if the scalaVersion you see in build.sbt is newer than 2.13, such as 2.18 for example, then go to

https://mvnrepository.com/artifact/org.scalaj/scalaj-http

to see the latest scalaj-http_2.18 version, such as 2.5.6 for example, and replace 2.4.2 with that version, as well as scalaj-http_2.13 with scalaj-http_2.18

A notification button appears within the window to the right - Load sbt Changes - click this floating button to update.

In your new scala project, browse to src -> Main.scala

Delete all the code in Main.scala and replace it with the scala search request code shown below: (without the line numbers - those are only for reference)

complete search request in scala with all default values shown explicitly - search type, text to search for (query), target list what to search for, in the case of POIs - also specify POI categories with poi_categs, ref_location a reference location in longitude and latitude around which to search; debug true causes resulting json to be pretty printed;

import scalaj.http.{Http, HttpOptions}
object Main
{
   def main(args: Array[String]): Unit =
   {
      val request = s"""
      {
         "type": "free_text",
         "text": "rest",
         "target": ["pois", "addresses"],
         "poi_categs": ["food&drink"],
         "ref_location": [4.89352, 52.36597],
         "max_results": 15,
         "exact_match": false,
         "fuzzy": false,
         "estimate_hno": true,
         "debug": true,
         "locale": "en"
      }
      """
      val result = Http("https://search.magiclaneapis.com/v1")
      .header("Content-Type", "application/json")
      .header("Authorization", "YOUR_API_KEY_TOKEN")
      .header("Accept-Encoding", "text")
      .postData(request)
      .option(HttpOptions.method("POST"))
      .option(HttpOptions.readTimeout(10000)).asString
      println(result)
      println(result.code)
   }
}

Click the green triangle play button to compile and run the scala search request!

Java

The java code shown has to be saved in a text file named JSONPostReq.java and then compiled; at the commandline on either a Linux terminal or Windows command prompt type:

javac JSONPostReq.java

to compile the program making the json POST request to the Maps REST API, and then run it:

java JSONPostReq

complete minimal java search request - search type, text to search for (query), target list what to search for, in the case of POIs - also specify POI categories with poi_categs, ref_location a reference location in longitude and latitude around which to search; debug true causes resulting json to be pretty printed;

import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.IOException;
public class JSONPostReq
{
   public static void main(String[] args) throws IOException
   {
      URL url = new URL("https://search.magiclaneapis.com/v1");
      HttpURLConnection connection = (HttpURLConnection) url.openConnection();
      connection.setRequestMethod("POST");
      connection.setDoOutput(true);
      connection.setRequestProperty("Content-Type","application/json");
      connection.setRequestProperty("Authorization","YOUR_API_KEY_TOKEN");
      String payload = "{"
         +"\"text\": \"rest\","
         +"\"target\": [\"pois\",\"addresses\"],"
         +"\"poi_categs\": [\"food&drink\"],"
         +"\"ref_location\": [4.89352, 52.36597],"
         +"\"debug\": true"
         +"}";
      byte[] out = payload.getBytes(StandardCharsets.UTF_8);
      OutputStream stream = connection.getOutputStream();
      stream.write(out);
      int responseCode = connection.getResponseCode();
      System.out.println("response code: "+responseCode);
      if (responseCode == HttpURLConnection.HTTP_OK)
      {
         BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
         String inputLine;
         while ((inputLine = in.readLine()) != null)
         {
            System.out.println(inputLine.toString());
         }
         in.close();
      }
      connection.disconnect();
   }
}

search request with all default values shown explicitly - this request is equivalent to, and produces the same output as, the previous request above;

import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.IOException;
public class JSONPostReq
{
   public static void main(String[] args) throws IOException
   {
   try
   {
      URL url = new URL("https://search.magiclaneapis.com/v1");
      HttpURLConnection connection = (HttpURLConnection) url.openConnection();
      connection.setRequestMethod("POST");
      connection.setDoOutput(true);
      connection.setRequestProperty("Content-Type","application/json");
      connection.setRequestProperty("Authorization","YOUR_API_KEY_TOKEN");
      String payload = "{"
         +"\"type\": \"free_text\","
         +"\"text\": \"rest\","
         +"\"target\": [\"pois\",\"addresses\"],"
         +"\"poi_categs\": [\"food&drink\"],"
         +"\"ref_location\": [4.89352, 52.36597],"
         +"\"max_results\": 15,"
         +"\"exact_match\": false,"
         +"\"fuzzy\": false,"
         +"\"estimate_hno\": true,"
         +"\"debug\": true,"
         +"\"locale\": \"en\""
         +"}";
      byte[] out = payload.getBytes(StandardCharsets.UTF_8);
      OutputStream stream = connection.getOutputStream();
      stream.write(out);
      int responseCode = connection.getResponseCode();
      System.out.println("response code: "+responseCode);
      System.out.println(connection.getResponseMessage());
      if (responseCode == HttpURLConnection.HTTP_OK)
      {
         BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
         StringBuffer response = new StringBuffer();
         String inputLine;
         while ((inputLine = in.readLine()) != null)
         {
            response.append(inputLine);
            System.out.println(inputLine.toString());
         }
         in.close();
         //System.out.println(response.toString());
      }
      else
      {
            System.out.println("POST request FAILED");
      }
      connection.disconnect();
   }
   catch (Exception e)
   {
      System.out.println(e);
      System.out.println("FAILED");
   }
   }
}

JavaScript

The javascript code shown can be saved in a text file such as search.js and run at the commandline using nodejs. In Linux, for example, if nodejs is not installed, it can be installed at the terminal commandline like this:

sudo apt install nodejs

also XMLHttpRequest needs to be installed:

npm install xhr2

Then search.js can be run at the commandline like this:

nodejs search.js

complete minimal javascript search request - search type, text to search for (query), target list what to search for, in the case of POIs - also specify POI categories with poi_categs, ref_location a reference location in longitude and latitude around which to search; debug true causes resulting json to be pretty printed;

var XMLHttpRequest = require("xhr2");
const xhr = new XMLHttpRequest();
xhr.open("POST", "https://search.magiclaneapis.com/v1");
xhr.setRequestHeader("Content-Type","application/json");
xhr.setRequestHeader("Authorization","YOUR_API_KEY_TOKEN");
const body = JSON.stringify({
   "text": "rest",
   "target": ["pois", "addresses"],
   "poi_categs": ["food&drink"],
   "ref_location": [4.89352, 52.36597],
   "debug": true
});
xhr.onload = () => {
   console.log((xhr.responseText));
};
xhr.send(body);

search request with all default values shown explicitly - this request is equivalent to, and produces the same output as, the previous request above;

var XMLHttpRequest = require("xhr2");
const xhr = new XMLHttpRequest();
xhr.open("POST", "https://search.magiclaneapis.com/v1");
xhr.setRequestHeader("Content-Type","application/json");
xhr.setRequestHeader("Authorization","YOUR_API_KEY_TOKEN");
const body = JSON.stringify({
   "type": "free_text",
   "text": "rest",
   "target": ["pois", "addresses"],
   "poi_categs": ["food&drink"],
   "ref_location": [4.89352, 52.36597],
   "max_results": 15,
   "exact_match": false,
   "fuzzy": false,
   "estimate_hno": true,
   "debug": true,
   "locale": "en"
});
xhr.onload = () => {
   if (xhr.readyState == 4 && xhr.status == 200) {
     console.log((xhr.responseText));
   } else {
     console.log(`error: ${xhr.status}`);
   }
};
xhr.send(body);

Go

The go code shown can be saved in a text file such as search.go and run at the commandline using go. In Linux, for example, if go is not installed, it can be installed at the terminal commandline like this:

sudo apt install golang

Then search.go can be run at the commandline like this:

go run search.go

complete minimal go search request:

package main
import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
)

func main() {
  reqUrl := "https://search.magiclaneapis.com/v1"
  var data = []byte(`{
    "text": "rest",
    "target": ["pois", "addresses"],
    "poi_categs": ["food&drink"],
    "ref_location": [4.89352, 52.36597],
    "debug": true
  }`)
  req, _ := http.NewRequest("POST", reqUrl, bytes.NewBuffer(data))
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "YOUR_API_KEY_TOKEN")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)
  fmt.Println(res)
  fmt.Println(string(body))
}

search request with all default values shown explicitly - this request is equivalent to, and produces the same output as, the previous request above;

package main
import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
)

func main() {
  reqUrl := "https://search.magiclaneapis.com/v1"
  var data = []byte(`{
    "type": "free_text",
    "text": "rest",
    "target": ["pois", "addresses"],
    "poi_categs": ["food&drink"],
    "ref_location": [4.89352, 52.36597],
    "max_results": 15,
    "exact_match": false,
    "fuzzy": false,
    "estimate_hno": true,
    "debug": true,
    "locale": "en"
  }`)
  req, _ := http.NewRequest("POST", reqUrl, bytes.NewBuffer(data))
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "YOUR_API_KEY_TOKEN")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)
  fmt.Println(res)
  fmt.Println(string(body))
}

Dart

https://dart.dev/get-dart Dart can be downloaded from here

To install dart on Linux (debian/ubuntu flavors), for example, it is best to download the .deb package from the Linux tab in the above link, such as dart_3.0.5-1_amd64.deb and install it like this:

sudo dpkg -i dart_3.0.5-1_amd64.deb

At a terminal/command prompt, type:

dart create myapp

to create a new dart application named myapp. A directory named myapp is created in the current directory, containing all necessary files. Go into this new directory:

cd myapp

User your favorite text editor, such as vim, geany or notepad to edit the pubspec.yaml file and add this dependency to the dependencies section as shown, then save it:

dependencies:

http: ^1.0.0

Next, edit the dart source code in lib/myapp.dart to look like this, without the line numbers - those are for reference only:

complete search request in dart with all default values shown explicitly -

import 'dart:io';
import 'dart:async';
import 'dart:convert';
import 'package:http/http.dart' as http;

calculate() async
{
   try
   {
      var sendString =
      {
          "type": "free_text",
          "text": "rest",
          "target": ["pois", "addresses"],
          "poi_categs": ["food&drink"],
          "ref_location": [4.89352, 52.36597],
          "max_results": 15,
          "exact_match": false,
          "fuzzy": false,
          "estimate_hno": true,
          "debug": true,
          "locale": "en"
      };
      final response = await http.post(
         Uri.parse("https://search.magiclaneapis.com/v1"),
         headers: {
            "Content-Type": "application/json",
            "Authorization": "YOUR_API_KEY_TOKEN"
            //"Access-Control-Allow-Origin": "*"
         },
         body: jsonEncode(sendString)
      );
      print("${response.statusCode}");//2 equivalent ways to print output
      //print("${response.body}");
      //print(response.statusCode);
      print(response.body);
   }
   catch(e)
   {
      print(e);
   }
}

You should replace the string “YOUR_API_KEY_TOKEN” with your actual API key token string. Now save the lib/myapp.dart file shown above, go to the myapp directory, and run it like this:

dart run

Perl

In Linux (debian/ubuntu flavors), for example, if perl is not installed, it can be installed at the terminal commandline like this:

sudo apt install perl

The JSON perl module can be installed like this:

sudo cpan JSON

complete minimal perl search request:

save this code in a text file named search.pl (without the line numbers - those are for reference) and run it:

perl search.pl

#! /usr/bin/env perl
use strict;
use warnings;
use LWP::UserAgent;
use HTTP::Request;
use JSON;

my $url = 'https://search.magiclaneapis.com/v1';
my $json = '{
      "text": "rest",
      "target": ["pois", "addresses"],
      "poi_categs": ["food&drink"],
      "ref_location": [4.89352, 52.36597],
      "debug": true
      }';
my $req = HTTP::Request->new( 'POST', $url );
$req->header( 'Content-Type' => 'application/json',
'Authorization' => 'YOUR_API_KEY_TOKEN');
$req->content( $json );
my $ua = LWP::UserAgent->new;
my $res = $ua->request( $req );
print $res->decoded_content;

search request with all default values shown explicitly - this request is equivalent to, and produces the same output as, the previous request above;

save this code in a text file named search.pl (without the line numbers - those are for reference) and run it:

perl search.pl

#! /usr/bin/env perl
use strict;
use warnings;
use LWP::UserAgent;
use HTTP::Request;
use JSON;

my $url = 'https://search.magiclaneapis.com/v1';
my $json = '{
      "type": "free_text",
      "text": "rest",
      "target": ["pois", "addresses"],
      "poi_categs": ["food&drink"],
      "ref_location": [4.89352, 52.36597],
      "max_results": 15,
      "exact_match": false,
      "fuzzy": false,
      "estimate_hno": true,
      "debug": true,
      "locale": "en"
      }';
my $req = HTTP::Request->new( 'POST', $url );
$req->header( 'Content-Type' => 'application/json',
'Authorization' => 'YOUR_API_KEY_TOKEN');
$req->content( $json );
my $ua = LWP::UserAgent->new;
my $res = $ua->request( $req );
print $res->decoded_content;

PHP

The php code shown can be saved in a text file such as search.php and run at the commandline using php.

In Linux (debian/ubuntu flavors), for example, if php is not installed, it can be installed at the terminal commandline like this:

sudo apt install php php-curl

Then search.php can be run at the commandline like this:

php search.php

complete minimal php search request:

<?php
$mycurl = curl_init("https://search.magiclaneapis.com/v1");
if ($mycurl === false) {
   print "curl initialization FAILED\n";
}
$payload = array(
      "text" => "rest",
      "target" => array("pois", "addresses"),
      "poi_categs" => array("food&drink"),
      "ref_location" => array(4.89352, 52.36597),
      "debug" => true
      );
$data_string = json_encode($payload);
curl_setopt($mycurl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($mycurl, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($mycurl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($mycurl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($mycurl, CURLOPT_HTTPHEADER, array(
   "Content-Type: application/json",
   "Authorization: YOUR_API_KEY_TOKEN"
   ));
$result = curl_exec($mycurl);

if ($result === false) {
   print "POST request FAILED " . curl_error($mycurl) . " errno: " . curl_errno($mycurl) . "\n";
}
else { var_dump($result); }

$httpReturnCode = curl_getinfo($mycurl, CURLINFO_HTTP_CODE);
if ($httpReturnCode != "200") {
   print "HTTP return code should be 200, got: " . $httpReturnCode . "\n";
}
if (is_resource($mycurl)) {
   curl_close($mycurl);
}
?>

search request with all default values shown explicitly - this request is equivalent to, and produces the same output as, the previous request above;

<?php
$mycurl = curl_init("https://search.magiclaneapis.com/v1");
if ($mycurl === false) {
   print "curl initialization FAILED\n";
}
$payload = array(
      "type" => "free_text",
      "text" => "rest",
      "target" => array("pois", "addresses"),
      "poi_categs" => array("food&drink"),
      "ref_location" => array(4.89352, 52.36597),
      "max_results" => 15,
      "exact_match" => false,
      "fuzzy" => false,
      "estimate_hno" => true,
      "debug" => true,
      "locale" => "en"
      );
$data_string = json_encode($payload);
//curl_setopt($mycurl, CURLOPT_URL, "https://search.magiclaneapis.com/v1");
curl_setopt($mycurl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($mycurl, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($mycurl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($mycurl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($mycurl, CURLOPT_HTTPHEADER, array(
   "Content-Type: application/json",
   "Authorization: YOUR_API_KEY_TOKEN"
   ));
$result = curl_exec($mycurl);

if ($result === false) {
   print "POST request FAILED " . curl_error($mycurl) . " errno: " . curl_errno($mycurl) . "\n";
}
else { var_dump($result); }

$httpReturnCode = curl_getinfo($mycurl, CURLINFO_HTTP_CODE);
if ($httpReturnCode != "200") {
   print "HTTP return code should be 200, got: " . $httpReturnCode . "\n";
}
if (is_resource($mycurl)) {
   curl_close($mycurl);
}
?>

R

In Linux (debian/ubuntu flavors), for example, if R is not installed, it can be installed at the terminal commandline like this:

sudo apt install r-base-dev

Then start the R interpreter environment like this:

R

install the httr package within R like this:

install.packages("httr")

and answer y to the two installation-related questions that follow;

complete minimal R search request: note that the debug parameter is omitted, as the json is stored in the response variable, not printed directly, so formatting the json output is done locally by the toJSON() function: pretty = TRUE; (copy and paste the code into the R interpreter, without the line numbers - those are for reference)

require(httr)
require(jsonlite)
body = '{
     "text": "rest",
     "target": ["pois", "addresses"],
     "poi_categs": ["food&drink"],
     "ref_location": [4.89352, 52.36597]
 }'
result <- POST("https://search.magiclaneapis.com/v1", body = body,
add_headers(.headers = c("Content-Type"="application/json", "Authorization"="YOUR_API_KEY_TOKEN")))
toJSON(content(result), pretty = TRUE)

search request with all default values shown explicitly - this request is equivalent to, and produces the same output as, the previous request above;

require(httr)
require(jsonlite)
body = '{
     "type": "free_text",
     "text": "rest",
     "target": ["pois", "addresses"],
     "poi_categs": ["food&drink"],
     "ref_location": [4.89352, 52.36597],
     "max_results": 15,
     "exact_match": false,
     "fuzzy": false,
     "estimate_hno": true,
     "debug": true,
     "locale": "en"
 }'
result <- POST("https://search.magiclaneapis.com/v1", body = body,
add_headers(.headers = c("Content-Type"="application/json", "Authorization"="YOUR_API_KEY_TOKEN")))
toJSON(content(result), pretty = TRUE)

To exit the R environment, type q()

Ruby

The ruby code shown can be saved in a text file such as search.rb and run at the commandline using ruby. In Linux, for example, if ruby is not installed, it can be installed at the terminal commandline like this:

sudo apt install ruby

Then search.rb can be run at the commandline like this:

ruby search.rb

complete minimal ruby search request:

require "json"
require "uri"
require "net/http"
require "openssl"

url = URI("https://search.magiclaneapis.com/v1")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Accept-Encoding"] = "text"
request["Authorization"] = "YOUR_API_KEY_TOKEN"
request.body =
{
    "text": "rest",
    "target": ["pois", "addresses"],
    "poi_categs": ["food&drink"],
    "ref_location": [4.89352, 52.36597],
    "debug": true
}.to_json
puts "sent"
response = http.request(request)
puts response.read_body

search request with all default values shown explicitly - this request is equivalent to, and produces the same output as, the previous request above;

require "json"
require "uri"
require "net/http"
require "openssl"

url = URI("https://search.magiclaneapis.com/v1")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Accept-Encoding"] = "text"
request["Authorization"] = "YOUR_API_KEY_TOKEN"
request.body =
{
    "type": "free_text",
    "text": "rest",
    "target": ["pois", "addresses"],
    "poi_categs": ["food&drink"],
    "ref_location": [4.89352, 52.36597],
    "max_results": 15,
    "exact_match": false,
    "fuzzy": false,
    "estimate_hno": true,
    "debug": true,
    "locale": "en"
}.to_json
puts "sent"
response = http.request(request)
puts response.read_body

Rust

Save the following in a text file named Cargo.toml (case-sensitive). This contains the configuration and dependencies required for compilation.

[package]
name = "restpost"
version = "0.1.0"
edition = "2018"

[[bin]]
name = "search"
path = "search.rs"

[dependencies]
json = { version = "0.12.4" }
reqwest = { version = "0.11.18", features = ["json", "blocking"] }
serde_json = { version = "1.0.44" }
tokio = { version = "1.28.2", features = ["macros", "full"] }

search request with all default values shown explicitly;

Save the following rust program in a text file named search.rs

extern crate reqwest;
#[tokio::main]
async fn main() -> Result<(), reqwest::Error>
{
   let response = reqwest::Client::new()
   .post("https://search.magiclaneapis.com/v1")
   .header("Authorization", "YOUR_API_KEY_TOKEN")
   .header("Content-Type", "application/json")
   .header("Accept-Encoding", "text")
   .json(&serde_json::json!({
      "type": "free_text",
      "text": "rest",
      "target": ["pois", "addresses"],
      "poi_categs": ["food&drink"],
      "ref_location": [4.89352, 52.36597],
      "max_results": 15,
      "exact_match": false,
      "fuzzy": false,
      "estimate_hno": true,
      "debug": true,
      "locale": "en"
      }))
      .send().await?;
   println!("{:?}",response.text().await?);
   Ok(())
}

In Linux (debian/ubuntu flavors), for example, if rust is not installed, it can be installed at the terminal commandline like this:

sudo apt install cargo rustc

Compile the program like this at the commandline, in the directory containing both Cargo.toml and search.rs:

cargo b

To run the program, go to the build directory like this:

cd target/debug

and then run the search program:

./search

Matlab

The Matlab code shown can be copied and pasted into Matlab, without the line numbers - those are for reference.

complete search request in Matlab with all default values shown explicitly -

method = matlab.net.http.RequestMethod.POST
f0 = matlab.net.http.HeaderField('Content-Type','application/json')
f1 = matlab.net.http.HeaderField('Authorization','')
header = [f0 f1]
str = [ ...
'{', ...
   + '"type": "free_text",', ...
   + '"text": "rest",', ...
   + '"target": ["pois","addresses"],', ...
   + '"poi_categs": ["food&drink"],', ...
   + '"ref_location": [4.89352, 52.36597],', ...
   + '"max_results": 15,', ...
   + '"exact_match": false,', ...
   + '"fuzzy": false,', ...
   + '"estimate_hno": true,', ...
   + '"debug": true,', ...
   + '"locale": "en"', ...
   + '}' ]
request = matlab.net.http.RequestMessage( method, header, jsondecode(str) );
response = request.send( 'https://search.magiclaneapis.com/v1' );
jsonencode(response.Body.Data,"PrettyPrint",true)

The above code can also be saved in a text file named search.m and run at the Matlab command prompt by typing search and pressing enter. The current working directory shown at the top of the window should be set to the directory where search.m was saved.

Scilab

The scilab code shown can be copied and pasted into scilab, without the line numbers - those are for reference.

https://www.scilab.org/ Scilab can be downloaded from here

complete minimal scilab search request: note that the debug parameter is omitted, as the json is stored in the result variable, not printed directly, so formatting the json output is done locally by the toJSON() function, where 3 is the number of spaces to use for indentation (if this number is 0, then the json output is not indented/pretty printed)

jsondata = ...
"{" ...
+"text: rest," ...
+"target: [pois,addresses]," ...
+"poi_categs: [food&drink]," ...
+"ref_location: [4.89352, 52.36597]" ...
+"}"
[result, status] = http_post("https://search.magiclaneapis.com/v1", toJSON(fromJSON(jsondata)), format="json", auth="YOUR_API_KEY_TOKEN" );
toJSON(result,3)

search request with all default values shown explicitly - this request is equivalent to, and produces the same output as, the previous request above;

jsondata = ...
"{" ...
+"type: free_text," ...
+"text: rest," ...
+"target: [pois,addresses]," ...
+"poi_categs: [food&drink]," ...
+"ref_location: [4.89352, 52.36597]," ...
+"max_results: 15," ...
+"exact_match: false," ...
+"fuzzy: false," ...
+"estimate_hno: true," ...
+"debug: true," ...
+"locale: en" ...
+"}"

[result, status] = http_post("https://search.magiclaneapis.com/v1", toJSON(fromJSON(jsondata)), format="json", auth="YOUR_API_KEY_TOKEN" );

toJSON(result,3)

In a linux terminal you can also send the request directly from the command line, without a file, like this: (this method does not work on windows)

curl "https://search.magiclaneapis.com/v1" -X POST -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_TOKEN" -d \
'{
...
}'

The only difference is the added backslash after -d, and then the filename @/home/user/payload.json is replaced with the contents of the json file, starting with the next line - note that a single quote ‘ is added before the leading curly brace { and after the trailing curly brace } to enclose the file contents in single quotes - no backslashes are needed between the single quotes.

Request parameter definitions

Request body schema: application/json
key	value
type	Search type - for “free_text” search, a search string must be provided as value for the “text” key; or, “around_location” - search type, search around given location specified by longitude, latitude coordinates to the “ref_location” key Type: string Default value: "free_text" Possible values - 1 of: “free_text”, “around_location”
text (conditional mandatory parameter)	String to search for - must be specified if search “type” is “free_text” Type: string Default value: empty
target	Target type to search for - if none specified, then the search result will contain only settlements/cities Type: string array Default value: none Possible values - 0 or more of: “pois”, “addresses”
poi_categs	If “pois” was included as value for the “target” key, the POI (point of interest) categories to search for can be specified using “poi_categs”; if no categories are specified, all are selected for the search Type: string array Default value: all categories selected for search Possible values - 0 or more of: “gas_stations”, “parking”, “food&drink”, “accommodation”, “medical_services”, “shopping”, “car_services”, “public_transport”, “wiki”, “education”, “entertainment”, “public_services”, “geographic_area”, “business”, “sightseeing”, “religious_places”, “roadside”, “sports”, “uncategorized”, “hydrants”, “emergency_services_support”, “civil_emergency_infrastructure”
poi_subcategs	If “pois” was included as value for the “target” key, the POI (point of interest) categories to search for can be specified using “poi_categs”; however, when searching for a specific type of POI, “poi_subcategs” offers a higher resolution to the search. Type: string array Default value: all subcategories of the specified “poi_categs” parent category are selected for search As an example, if the category “food&drink” is specified for “poi_categs”, this includes all “poi_subcategs” for “food&drink”; however, if searching specifically for a tea house or coffee shop, then, instead of specifying the entire [“food&drink”] parent category for “poi_categs”, specify the subcategories [“tea_house”,”coffee_shop”] for “poi_subcategs”. These are the POI subcategories for each of the POI categories shown in “poi_categs” above:

Select a POI category to see its POI subcategories:

Gas Stations

petrol_station

charging_station

bicycle_charging_station

Parking

park_and_ride

parking_garage

parking_lot

bicycle_parking

rv_park

truck_parking

truck_stop

parking_meter

Food & Drink

bar

coffee_shop

restaurant

specialty_food_store

tea_house

wine_and_spirits

winery

drinking_water

fast_food

bakery

Accommodation

camping

hotel

accommodation

utilities

alpine_hut

chalet

booking.com_hotel

Medical Services

dentist

health_care_service

hospital

medical_service

optician

pharmacy

physician

retirement_home

veterinarian

emergency_service

Shopping

automobile_dealership

bookstore

bicycle_shop

clothing_store

electronics_store

convenience_store

department_store

discount_store

entertainment_electronics

floor_coverings_and_carpets

flowers

furniture

garden_centre

gift_shop

glass_and_windows

grocery

hairdresser

hardware_store

home_improvement_centre

home_improvement

home_specialty_store

lottery_shop

major_appliance

men's apparel

motorcycle_dealership

office_supply_store

other_general_merchandise

paint_shop

photography

music

shoe_store

shopping

specialty_clothing_store

specialty_store

sporting_goods_store

variety_store

women's apparel

agriculture

butcher

jewellery

do_it_yourself

vending_machine

bicycle_tube_vending_machine

cigarettes_vending_machine

coffee_vending_machine

drinks_vending_machine

food_vending_machine

newspaper_vending_machine

Car Services

auto_dealership_-_used_cars

auto_parts

auto_service

automobile_club

car_wash

rental_car_agency

car_sharing

Public Transport

airport

bicycle_rental

bus_station

commuter_train_station

ferry_terminal

local_transit

marina

subway_entrance

public_transit_stop

ski_lift

taxi_stand

train_station

transportation_service

subway_station

helipad

tram_station

public_transit_tickets_kiosk

Wiki

wikipedia

Education

higher_education

library

school

science_and_research_institute

Entertainment

amusement_park

animal_park

banquet_hall

casino

cinema

cocktail_lounge

night_club

nightlife

performing_arts

video_rental

Public Services

city_hall

civic_centre

convention_centre

county_council

court_house

embassy

fire_station

government_office

military_base

police_service

police_station

post_office

public_toilets

social_service

waste_and_sanitary

child_care_centre

recycling

animal_waste_bags_dispenser

parcel_locker

Geographic Area

border_crossing

recreation_area

playground

peak

cave

archaeological_site

water

island

national_park

forest

Business

atm

bank

boats

business_facility

business_services

cheque_cashing_service

dry_cleaning_and_laundry

computers_and_software

currency_exchange

funeral_director

industrial

timber

money_transferring_service

mover

communication

real_estate_agency

repair_service

storage

tailor_shop

tax_services

telecom

toll_station

travel_agent

weigh_station

attorney

bicycle_service

route_66

Sightseeing

historical_monument

museum

tourist_attraction

tourist_information

windmill

viewpoint

lighthouse

Religious Places

cemetery

church

place_of_worship

synagogue

mosque

temple

Roadside

highway_exit

race_track

rest_area

road_assistance

shelter

traffic_light

stop_sign

give_way_sign

traffic_calming

pedestrian_traffic_light

bicycle_traffic_light

pedestrian_crossing

Sports

bowling_centre

golf_course

golf_practice_range

health_club

ice_skating

swimming_pool

recreation

ski_resort

sporting_and_instructional_camp

sports_activities

sports_centre

sports_complex

Uncategorized

tree

rope

loading_dock

Hydrants

fire_hydrant

pillar_hydrant

underground_hydrant

wall_hydrant

water_tank_hydrant

pond_hydrant

pipe_hydrant

Emergency Services Support

defibrillator

first_aid_kit

ambulance_station

emergency_phone

emergency_landing_site

emergency_ward_entrance

emergency_ward_entrance_-_rescue_service

emergency_ward_entrance_-_walk_in

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

siren

fire_siren

civil_defense_siren

tornado_siren

tsunami_siren

air_raid_siren

Request body schema: application/json (continued from above)
key	value
ref_location (conditional mandatory parameter)	Longitude, latitude reference location for the search - must be specified if search “type” is “around_location” Type: array of 2 doubles in format [lon, lat]
max_results	Specify maximum number of search results to return Type: integer Default value: 15
exact_match	If true, only exact word matches for the search string filter are returned in the results Type: bool Default value: false
fuzzy	If true, enables search string filter corrections using a fuzzy algorithm when no results are found Type: bool Default value: true
estimate_hno	If true, when only start and end house numbers are present on a street, an estimation of the searched house number is made, using an interpolation algorithm Type: bool Default value: true
debug	If true, the JSON output is formatted for easy reading Type: bool Default value: false
locale	The ISO 639-1 language for the search result Type: string Default value: en

Response

MagicLane header

{
  "info": {
    "copyrights": [
      "MagicLane"
    ]
  },
  "results": [

Search results

Each result item is given in a JSON block as shown below.

The coordinates in longitude, latitude (degrees). Location name, description and address components. Location contact details, such as phone number, email and URL, if available. Also wikipedia info and native location name, if available, and distance from reference location, in meters.

{
   "coordinates": [
     4.8887434374999996223,
     52.357778125000002944
   ],
   "name": "Le Restaurant",
   "description": "Restaurant",
   "address": {
     "street name": "Frans Halsstraat",
     "street number": "26-H",
     "settlement": "Zuid",
     "city": "Amsterdam",
     "county": "North Holland",
     "country": "Netherlands",
     "country code": "NLD"
   },
   "contact": {
     "URL": "https://www.le-restaurant.nl"
   },
   "native_name": "Le Restaurant",
   "distance": 966
},