Documentation
MasterForm web
Masterform Web makes it possible to easily distribute the form for autocompletion of addresses.
Basic application
Import of css and 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>
Defining of form-like elements, that we want to use for autocompletion:
const placeEl = document.getElementById('place')
const cityEl = document.getElementById('city')
const postCodeEl = document.getElementById('postCode')
Initialization of MasterForm:
const masterForm = MasterForm.init('webKey')webKey is accessible in our administration.
Setting of the autocompletion:
// Autocompletion of places of address
masterForm.place({
'place': placeEl,
'city': cityEl,
'postCode': postCodeEl,
'countryCode': 'de'
})
// Autocompletion of municipalities
masterForm.city({
'city': cityEl,
'countryCode': 'de'
})
With all objects, it is possible to set up countryCode as a form-like element. MasterForm will be automatically detect the country chosen by the user :
masterForm.place({
'place': placeEl,
'city': cityEl,
'postCode': postCodeEl,
'countryCode': document.getElementById('countryCode')
})
Further possibilities
Přenastavení již inicializovaného objektu:
// Standard initialisation
masterForm.place({
'place': placeEl,
'city': cityEl,
'postCode': postCodeEl,
'countryCode': 'de'
})
// Adjustment of the setting
document.querySelector('.some-element').addEventListener('click', function (e) {
masterForm.setSettings({
'countryCode': 'fr'
})
})
Callback function
const masterForm = MasterForm.init('webKey', {
// Item in the autocompletion
'onValueItem': function (data) {
return '<div class="custom-output">' + data.suggestionValue + '</div>'
},
// After the chosen item in the autocompletion
'onCompletedSelectedItem': function (data) {
console.log(data)
}
})Design of the autocompletion
Setting of the design:
const masterForm = init('webKey', {
'theme': 'default' // default, classic, modern
})
Individually for separate objects:
masterForm.place({
'theme': 'modern'
...
})
Individual design of the autocompletion
Definition of an individual class
const masterForm = init('webKey', {
'theme': 'custom-theme'
})
.masterform-v1 .custom-theme {}
MasterForm API
Each demand is called upon by means of POST methods, it includes API key (you will find it in administration) and it includes JSON string in the body.
API Endpoints
Url api: https://api.masterform.cz
Available endpoints:
- /v1/autocomplete/place (autocompletion of places )
- /v1/autocomplete/city (autocompletion of municipalities)
Autocompletion of places of address
Requirement
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 parameters
| Title | Type | Default value | Mandatory | Description |
|---|---|---|---|---|
query.place |
string | Yes | Name of the place of address | |
query.city |
string | No | City name. If it is filled out, places of address will be limited to this merit. | |
query.postCode |
string | No | Zip code. If it is filled out, places of address or cities will be limited to this merit. | |
query.countryCode |
string |
de
|
No | Country code. Limits the search results to the chosen country. |
limit |
int |
10
|
No | Number of items in the search results. Maximum number is 50. |
Answer
{
"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"
}
}
]
}
Autocompletion of municipalities
Requirement
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 parameters
| Title | Type | Default value | Mandatory | Description |
|---|---|---|---|---|
query.city |
string | Yes | Name of the municipality | |
query.countryCode |
string |
de
|
No | Country code. Limits the search results to the chosen country. |
limit |
int |
10
|
No | Number of items in the search results. Maximum number is 50. |
Answer
{
"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"
}
}
]
}