Search

_{Estimated reading time: 31 minutes}

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://routes.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
},