MasterForm web
Základní použití Další možnosti Callback funkce Vzhled našeptávače Vlastní vzhled našeptávače
MasterForm API
API Endpoints Našeptávání adresních míst Našeptávání obcí

Dokumentace

MasterForm web

Masterform Web umožňuje jednoduše rozšířit formulář o našeptávání poštovních adres.

Základní použití

Import css a js:

<link rel="stylesheet" href="https://api.masterform.cz/bundle/v1/masterform-style.css">
<script type="text/javascript" src="https://api.masterform.cz/bundle/v1/masterform.js"></script>

Definování formulářových elementů, které chceme použít pro našeptávání:

const placeEl = document.getElementById('place')
const cityEl = document.getElementById('city')
const postCodeEl = document.getElementById('postCode')

Inicializace MasterForm:

const masterForm = MasterForm.init('webKey')

webKey je dostupný ve vaši administraci.

Nastavení našeptávače:

// Našeptávání adresních míst
masterForm.place({
    'place': placeEl,
    'city': cityEl,
    'postCode': postCodeEl,
    'countryCode': 'de'
})

// Našeptávání obcí
masterForm.city({
    'city': cityEl,
    'countryCode': 'de'
})

U všech objektů je možné nastavit countryCode jako formulářový element. MasterForm bude automaticky detekovat uživatelem zvolený stát:

masterForm.place({
    'place': placeEl,
    'city': cityEl,
    'postCode': postCodeEl,
    'countryCode': document.getElementById('countryCode')
})

Další možnosti

Přenastavení již inicializovaného objektu:

// Standardní inicializace
masterForm.place({
    'place': placeEl,
    'city': cityEl,
    'postCode': postCodeEl,
    'countryCode': 'de'
})

// Úprava nastavení
document.querySelector('.some-element').addEventListener('click', function (e) {
    masterForm.setSettings({
        'countryCode': 'fr'
    })
})

Callback funkce

const masterForm = MasterForm.init('webKey', {
    // Položka v našeptávači
    'onValueItem': function (data) {
        return '<div class="custom-output">' + data.suggestionValue + '</div>'
    },

    // Po vybrané položce v našeptávači
    'onCompletedSelectedItem': function (data) {
        console.log(data)
    }
})

Vzhled našeptávače

Nastavení vzhledu:

const masterForm = init('webKey', {
    'theme': 'default' // default, classic, modern
})

Individuálně pro jednotlivé objekty:

masterForm.place({
    'theme': 'modern'
    ...
})

Vlastní vzhled našeptávače

Definování vlastní css třídy:

const masterForm = init('webKey', {
    'theme': 'custom-theme'
})

.masterform-v1 .custom-theme {}

MasterForm API

Každý požadavek je volaný pomocí POST metody, obsahuje API klíč (najdete v administraci) a obsahuje JSON řetězec v body.

API Endpoints

Url api: https://api.masterform.cz

Dostupné endpoints:

  • /v1/autocomplete/place (našeptávání míst)
  • /v1/autocomplete/city (našeptávání obcí)

Našeptávání adresních míst

Požadavek

curl --request POST \ --url 'https://api.masterform.cz/v1/autocomplete/place' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "query": { "place": "kufners", "city": "", "postCode": "", "countryCode": "de" }, "limit": "10" }'
// Maven : Add these dependecies to your pom.xml (java6+) // <dependency> // org.glassfish.jersey.core // jersey-client // 2.8 // </dependency> // <dependency> // org.glassfish.jersey.media // jersey-media-json-jackson // 2.8 // </dependency> import javax.ws.rs.client.Client; import javax.ws.rs.client.ClientBuilder; import javax.ws.rs.client.Entity; import javax.ws.rs.core.Response; import javax.ws.rs.core.MediaType; Client client = ClientBuilder.newClient(); Entity payload = Entity.json("{\"query\":{\"place\":\"kufners\",\"city\":\"\",\"postCode\":\"\",\"countryCode\":\"de\"},\"limit\":\"10\"}"); Response response = client.target("https://api.masterform.cz/v1/autocomplete/place") .request(MediaType.APPLICATION_JSON_TYPE) .header("Authorization", "Bearer YOUR_API_KEY") .post(payload); System.out.println("status: " + response.getStatus()); System.out.println("headers: " + response.getHeaders()); System.out.println("body:" + response.readEntity(String.class));
var request = new XMLHttpRequest() request.open('POST', 'https://api.masterform.cz/v1/autocomplete/place') request.setRequestHeader('Content-Type', 'application/json') request.setRequestHeader('Authorization', 'Bearer YOUR_API_KEY'); request.onreadystatechange = function () { if (this.readyState === 4) { console.log('Status:', this.status) console.log('Headers:', this.getAllResponseHeaders()) console.log('Body:', this.responseText) } } const body = { "query": { "place": "kufners", "city": "", "postCode": "", "countryCode": "de" }, "limit": "10" } request.send(JSON.stringify(body));
let request = require('request') request({ method: 'POST', url: 'https://api.masterform.cz/v1/autocomplete/place', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' }, body: "{\"query\":{\"place\":\"kufners\",\"city\":\"\",\"postCode\":\"\",\"countryCode\":\"de\"},\"limit\":\"10\"}" }, function (error, response, body) { console.log('Status:', response.statusCode) console.log('Headers:', JSON.stringify(response.headers)) console.log('Response:', body) })
$ENV{'PERL_LWP_SSL_VERIFY_HOSTNAME'} = 0; use LWP::UserAgent; use strict; use warnings; use 5.010; use Cpanel::JSON::XS qw(encode_json decode_json); my $ua = LWP::UserAgent->new; my $data = '{"query":{"place":"kufners","city":"","postCode":"","countryCode":"de"},"limit":"10"}'; $ua->default_header("Content-Type" => "application/json"); $ua->default_header("Authorization" => "Bearer YOUR_API_KEY"); my $response = $ua->post("https://api.masterform.cz/v1/autocomplete/place", Content => $data); print $response->as_string;
from urllib2 import Request, urlopen values = """ { "query": { "place": "kufners", "city": "", "postCode": "", "countryCode": "de" }, "limit": "10" } """ headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' } request = Request('https://api.masterform.cz/v1/autocomplete/place', data=values, headers=headers) response_body = urlopen(request).read() print response_body
<?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://api.masterform.cz/v1/autocomplete/place"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, '{ "query": { "place": "kufners", "city": "", "postCode": "", "countryCode": "de" }, "limit": "10" }') curl_setopt($ch, CURLOPT_HTTPHEADER, array( "Content-Type: application/json", "Authorization: Bearer YOUR_API_KEY" )); $response = curl_exec($ch); curl_close($ch); var_dump($response);
require 'rubygems' if RUBY_VERSION < '1.9' require 'rest_client' values = '{ "query": { "place": "kufners", "city": "", "postCode": "", "countryCode": "de" }, "limit": "10" }' headers = { :content_type => 'application/json', :authorization => 'Bearer YOUR_API_KEY' } response = RestClient.post 'https://api.masterform.cz/v1/autocomplete/place', values, headers puts response
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses. //System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; }; //Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line. using System; using System.Net.Http; var baseAddress = new Uri("https://api.masterform.cz/"); using (var httpClient = new HttpClient{ BaseAddress = baseAddress }) { httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Bearer YOUR_API_KEY"); using (var content = new StringContent("{\"query\":{\"place\":\"kufners\",\"city\":\"\",\"postCode\":\"\",\"countryCode\":\"de\"},\"limit\":\"10\"}")) { using (var response = await httpClient.PostAsync("v1/place", content)) { string responseData = await response.Content.ReadAsStringAsync(); } } }

JSON parametry:

Název Typ Výchozí hodnota Povinný Popis
query.place string Ano Název adresního místa
query.city string Ne Název města. Pokud je vyplněno, tak se adresní místa omezí na tuto hodnotu.
query.postCode string Ne PSČ. Pokud je vyplněno, tak se adresní místa nebo města omezí na tuto hodnotu.
query.countryCode string de Ne Kód státu. Omezuje výsledky vyhledávání pro zvolený stát.
limit int 10 Ne Počet položek ve výsledku vyhledávání. Maximální hodnota je 50.

Odpověď

{
    "status": "success",
    "code": 200,
    "items": [
        {
            "type": "place",
            "isCompleted": false,
            "suggestionValue": "Küfnersgewend",
            "values": {
                "countryCode": "de"
            }
        },
        {
            "type": "place",
            "isCompleted": false,
            "suggestionValue": "Küfnerstraße",
            "values": {
                "countryCode": "de"
            }
        },
        {
            "type": "place",
            "isCompleted": true,
            "suggestionValue": "Küfnersgewend 4, 95463 Bindlach",
            "values": {
                "number": "4",
                "street": "Küfnersgewend",
                "locality": "",
                "city": "Bindlach",
                "district": "Landkreis Bayreuth",
                "region": "Bayern",
                "postCode": "95463",
                "placeAndNumber": "Küfnersgewend 4",
                "address": "Küfnersgewend 4, 95463 Bindlach",
                "id": "PdrWJIwBx9OKiBfac9wo",
                "countryCode": "de"
            }
        },
        {
            "type": "place",
            "isCompleted": true,
            "suggestionValue": "Küfnerstraße 10, 81927 München",
            "values": {
                "number": "10",
                "street": "Küfnerstraße",
                "locality": "",
                "city": "München",
                "district": "",
                "region": "Bayern",
                "postCode": "81927",
                "placeAndNumber": "Küfnerstraße 10",
                "address": "Küfnerstraße 10, 81927 München",
                "id": "LenYJIwBx9OKiBfaMWbL",
                "countryCode": "de"
            }
        },
        {
            "type": "place",
            "isCompleted": true,
            "suggestionValue": "Küfnersgewend 2, 95463 Bindlach",
            "values": {
                "number": "2",
                "street": "Küfnersgewend",
                "locality": "",
                "city": "Bindlach",
                "district": "Landkreis Bayreuth",
                "region": "Bayern",
                "postCode": "95463",
                "placeAndNumber": "Küfnersgewend 2",
                "address": "Küfnersgewend 2, 95463 Bindlach",
                "id": "R9rWJIwBx9OKiBfac9wo",
                "countryCode": "de"
            }
        },
        {
            "type": "place",
            "isCompleted": true,
            "suggestionValue": "Küfnersgewend 6a, 95463 Bindlach",
            "values": {
                "number": "6a",
                "street": "Küfnersgewend",
                "locality": "",
                "city": "Bindlach",
                "district": "Landkreis Bayreuth",
                "region": "Bayern",
                "postCode": "95463",
                "placeAndNumber": "Küfnersgewend 6a",
                "address": "Küfnersgewend 6a, 95463 Bindlach",
                "id": "StrWJIwBx9OKiBfac9wo",
                "countryCode": "de"
            }
        },
        {
            "type": "place",
            "isCompleted": true,
            "suggestionValue": "Küfnersgewend 6b, 95463 Bindlach",
            "values": {
                "number": "6b",
                "street": "Küfnersgewend",
                "locality": "",
                "city": "Bindlach",
                "district": "Landkreis Bayreuth",
                "region": "Bayern",
                "postCode": "95463",
                "placeAndNumber": "Küfnersgewend 6b",
                "address": "Küfnersgewend 6b, 95463 Bindlach",
                "id": "D9vWJIwBx9OKiBfadxyx",
                "countryCode": "de"
            }
        },
        {
            "type": "place",
            "isCompleted": true,
            "suggestionValue": "Küfnersgewend 8, 95463 Bindlach",
            "values": {
                "number": "8",
                "street": "Küfnersgewend",
                "locality": "",
                "city": "Bindlach",
                "district": "Landkreis Bayreuth",
                "region": "Bayern",
                "postCode": "95463",
                "placeAndNumber": "Küfnersgewend 8",
                "address": "Küfnersgewend 8, 95463 Bindlach",
                "id": "EtvWJIwBx9OKiBfadxyx",
                "countryCode": "de"
            }
        }
    ]
}

Našeptávání obcí

Požadavek

curl --request POST \ --url 'https://api.masterform.cz/v1/autocomplete/city' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "query": { "city": "mun", "countryCode": "de" }, "limit": "10" }'
// Maven : Add these dependecies to your pom.xml (java6+) // <dependency> // org.glassfish.jersey.core // jersey-client // 2.8 // </dependency> // <dependency> // org.glassfish.jersey.media // jersey-media-json-jackson // 2.8 // </dependency> import javax.ws.rs.client.Client; import javax.ws.rs.client.ClientBuilder; import javax.ws.rs.client.Entity; import javax.ws.rs.core.Response; import javax.ws.rs.core.MediaType; Client client = ClientBuilder.newClient(); Entity payload = Entity.json("{\"query\":{\"city\":\"mun\",\"countryCode\":\"de\"},\"limit\":\"10\"}"); Response response = client.target("https://api.masterform.cz/v1/autocomplete/city") .request(MediaType.APPLICATION_JSON_TYPE) .header("Authorization", "Bearer YOUR_API_KEY") .post(payload); System.out.println("status: " + response.getStatus()); System.out.println("headers: " + response.getHeaders()); System.out.println("body:" + response.readEntity(String.class));
var request = new XMLHttpRequest() request.open('POST', 'https://api.masterform.cz/v1/autocomplete/city') request.setRequestHeader('Content-Type', 'application/json') request.setRequestHeader('Authorization', 'Bearer YOUR_API_KEY'); request.onreadystatechange = function () { if (this.readyState === 4) { console.log('Status:', this.status) console.log('Headers:', this.getAllResponseHeaders()) console.log('Body:', this.responseText) } } const body = { "query": { "city": "mun", "countryCode": "de" }, "limit": "10" } request.send(JSON.stringify(body));
let request = require('request') request({ method: 'POST', url: 'https://api.masterform.cz/v1/autocomplete/city', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' }, body: "{\"query\":{\"city\":\"mun\",\"countryCode\":\"de\"},\"limit\":\"10\"}" }, function (error, response, body) { console.log('Status:', response.statusCode) console.log('Headers:', JSON.stringify(response.headers)) console.log('Response:', body) })
$ENV{'PERL_LWP_SSL_VERIFY_HOSTNAME'} = 0; use LWP::UserAgent; use strict; use warnings; use 5.010; use Cpanel::JSON::XS qw(encode_json decode_json); my $ua = LWP::UserAgent->new; my $data = '{"query":{"city":"mun","countryCode":"de"},"limit":"10"}'; $ua->default_header("Content-Type" => "application/json"); $ua->default_header("Authorization" => "Bearer YOUR_API_KEY"); my $response = $ua->post("https://api.masterform.cz/v1/autocomplete/city", Content => $data); print $response->as_string;
from urllib2 import Request, urlopen values = """ { "query": { "city": "mun", "countryCode": "de" }, "limit": "10" } """ headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' } request = Request('https://api.masterform.cz/v1/autocomplete/city', data=values, headers=headers) response_body = urlopen(request).read() print response_body
<?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://api.masterform.cz/v1/autocomplete/city"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, '{ "query": { "city": "mun", "countryCode": "de" }, "limit": "10" }') curl_setopt($ch, CURLOPT_HTTPHEADER, array( "Content-Type: application/json", "Authorization: Bearer YOUR_API_KEY" )); $response = curl_exec($ch); curl_close($ch); var_dump($response);
require 'rubygems' if RUBY_VERSION < '1.9' require 'rest_client' values = '{ "query": { "city": "mun", "countryCode": "de" }, "limit": "10" }' headers = { :content_type => 'application/json', :authorization => 'Bearer YOUR_API_KEY' } response = RestClient.post 'https://api.masterform.cz/v1/autocomplete/city', values, headers puts response
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses. //System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; }; //Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line. using System; using System.Net.Http; var baseAddress = new Uri("https://api.masterform.cz/"); using (var httpClient = new HttpClient{ BaseAddress = baseAddress }) { httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Bearer YOUR_API_KEY"); using (var content = new StringContent("{\"query\":{\"city\":\"mun\",\"countryCode\":\"de\"},\"limit\":\"10\"}")) { using (var response = await httpClient.PostAsync("v1/city", content)) { string responseData = await response.Content.ReadAsStringAsync(); } } }

JSON parametry:

Název Typ Výchozí hodnota Povinný Popis
query.city string Ano Název obce
query.countryCode string de Ne Kód státu. Omezuje výsledky vyhledávání pro zvolený stát.
limit int 10 Ne Počet položek ve výsledku vyhledávání. Maximální hodnota je 50.

Odpověď

{
    "status": "success",
    "code": 200,
    "items": [
        {
            "type": "city",
            "isCompleted": true,
            "suggestionValue": "München",
            "values": {
                "countryCode": "de",
                "city": "München",
                "id": "d-TXJIwBx9OKiBfasvaY"
            }
        },
        {
            "type": "city",
            "isCompleted": true,
            "suggestionValue": "Münster",
            "values": {
                "countryCode": "de",
                "city": "Münster",
                "id": "_oDOJIwBx9OKiBfai5FQ"
            }
        },
        {
            "type": "city",
            "isCompleted": true,
            "suggestionValue": "Bad Münstereifel",
            "values": {
                "countryCode": "de",
                "city": "Bad Münstereifel",
                "id": "Ip3QJIwBx9OKiBfamxMa"
            }
        },
        {
            "type": "city",
            "isCompleted": true,
            "suggestionValue": "Münsingen",
            "values": {
                "countryCode": "de",
                "city": "Münsingen",
                "id": "5bDSJIwBx9OKiBfaQ_TG"
            }
        },
        {
            "type": "city",
            "isCompleted": true,
            "suggestionValue": "Korntal-Münchingen",
            "values": {
                "countryCode": "de",
                "city": "Korntal-Münchingen",
                "id": "C7rTJIwBx9OKiBfaDilw"
            }
        },
        {
            "type": "city",
            "isCompleted": true,
            "suggestionValue": "Grafing bei München",
            "values": {
                "countryCode": "de",
                "city": "Grafing bei München",
                "id": "B-rYJIwBx9OKiBfaW9y9"
            }
        },
        {
            "type": "city",
            "isCompleted": true,
            "suggestionValue": "Bad Münder am Deister",
            "values": {
                "countryCode": "de",
                "city": "Bad Münder am Deister",
                "id": "0DHiJIwBx9OKiBfacE1N"
            }
        },
        {
            "type": "city",
            "isCompleted": true,
            "suggestionValue": "Münster (Hessen)",
            "values": {
                "countryCode": "de",
                "city": "Münster (Hessen)",
                "id": "78zVJIwBx9OKiBfaB_Ge"
            }
        },
        {
            "type": "city",
            "isCompleted": true,
            "suggestionValue": "Garching bei München",
            "values": {
                "countryCode": "de",
                "city": "Garching bei München",
                "id": "VefXJIwBx9OKiBfa8l45"
            }
        },
        {
            "type": "city",
            "isCompleted": true,
            "suggestionValue": "Müncheberg",
            "values": {
                "countryCode": "de",
                "city": "Müncheberg",
                "id": "YFzqJIwBx9OKiBfaAUMK"
            }
        }
    ]
}
Vyzkoušet zdarma
EN DE CS