For developers - API (alpha)

Base URL for all API services: http://www.mytravelmap.xyz/api/v1/
Latest API version is v1 as indicated in the URL.

All requests to our API must contain application key (passed as appKey parameter). Please, send us an email to [email protected] to get your own application key. Together with the application key you will be given an application shared secret (referred to as APP_SHARED_SECRET), which you must keep secure at all times! Note, that application shared secret should never be sent over the network as part of a request!

Using testing app key

For testing purposes and to evaluate our API first, you may use "TESTAPPKEY000000" application key. When using this specific application key, signing of the requests (calculation of the 'sig' parameter) is not necessary. In such case, there is a hard limit of total number of requests per minute! If the hard limit is exceeded, a response with a status code 429 Too Many Requests will be returned! Note, that this very same application key is shared globally with everyone, therefore reaching the allowance of total number of requests per minute might be a common case. As such, its use is meant for development only! The validity of this application key might be discontinued anytime without a prior notice!

Services

1) Generate world map

Endpoint: GET world.{FILE_TYPE}
Resource URL: http://www.mytravelmap.xyz/api/v1/world.{FILE_TYPE}
FILE_TYPE: json - generates JSON response with detailed textual information of the resulting image
png - generates actual image in PNG format

Parameters

Name Required Description Default value Example
appKey Yes Application identifier JKUmj2fjJMgOQs3Y
width Yes Image width (px) (max 2050) 1024
height Yes Image height (px) (max 2050) 512
bgColor No Image background color
(either 6 hexadecimal RGB or 8 hexadecimal RGBA)
ffffff RGB - c0c0c0
RGBA - c0c0c099
fgColor No Image foreground color
(either 6 hexadecimal RGB or 8 hexadecimal RGBA)
a9a9a9 RGB - c0c0c0
RGBA - c0c0c099
geo No (possible to use multiple times) List of GPS coordinates colored with a specified color.
At least one GPS coordinate (in the format lat,lon) has to be specified.
Value format either '[email protected],lon|...' or '[email protected],lon|...'
[email protected],13.851300
[email protected],13.851300|32.548774,35.857268
[email protected],13.851300|32.548774,35.857268|3.113924,101.617261
[email protected],13.851300
[email protected],13.851300|32.548774,35.857268
[email protected],13.851300|32.548774,35.857268|3.113924,101.617261
pin No (possible to use multiple times) List of GPS coordinates colored with a specified color.
At least one GPS coordinate (in the format lat,lon) has to be specified.
Value format either '[email protected],lon|...' or '[email protected],lon|...'

The pins will always be placed in the middle of country which contains the GPS coordinate!
[email protected],13.851300
[email protected],13.851300|32.548774,35.857268
[email protected],13.851300|32.548774,35.857268|3.113924,101.617261
[email protected],13.851300
[email protected],13.851300|32.548774,35.857268
[email protected],13.851300|32.548774,35.857268|3.113924,101.617261
pinScale No Size of the pin.
This attribute will have an effect only when used together with pin attribute.
0.3 0.75
pinLabelColor No Color of the label (country name) displayed above the pin.
This attribute will have an effect only when used together with pinLabelSize attribute.
(either 6 hexadecimal RGB or 8 hexadecimal RGBA)
000000 RGB - c0c0c0
RGBA - c0c0c099
pinLabelFont No Font family of the label (country name) displayed above the pin.
This attribute will have an effect only when used together with pinLabelSize attribute.
sans-serif sans-serif, serif, Arial,...
pinLabelLocale No Locale of the label (country name) displayed above the pin.
This attribute will have an effect only when used together with pinLabelSize attribute.
en All supported locales:
Albanian (sq), Arabic (ar), Belarusian (be), Bengali (bn), Bulgarian (bg), Burmese (my), Catalan (ca), Chinese (zh-CN), Chinese (zh-TW), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), Estonian (et), Filipino (fil), Finnish (fi), French (fr), Georgian (ka), German (de), Greek (el), Hebrew (he), Hindi (hi), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Latvian (lv), Lithuanian (lt), Malay (ms), Mongolian (mn), Norwegian (no), Persian (fa), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Serbian (sr), Slovak (sk), Slovenian (sl), Spanish (es), Swedish (sv), Thai (th), Turkish (tr), Ukrainian (uk), Uzbek (uz), Vietnamese (vi)
pinLabelSize No Size of the label (country name) displayed above the pin. Unit is pt.
All the other pinLabel* attributes will have effect only if this attribute is a positive integer.
0 6
pinLabelWeight No Font weight of the label (country name) displayed above the pin.
This attribute will have an effect only when used together with pinLabelSize attribute.
normal normal, bold
sig Yes (when using your app key)
No (when using testing app key)
Request signature which is created for security reasons bf72dbe5fb6f588ff3df6fcb23587b220c204da3

Creating a Request Signature

The parameter sig equals SHA1 from the concatenation of the following strings:
Calculate the 'sig' value as sha1(concatenatedParametersAPP_SHARED_SECRET)

Pseudocode:
	
  $sign = '';
  foreach ($sortedUrlParameters as $key => $value) {
    if ($key != 'sig') {
	 $sign .= ($key.'='.$value);
    }
  }
  $sign .= APP_SHARED_SECRET;
  $sign = sha1($sign);
	
  
An example how to calculate the signature:
  1. Application key: SomeAppKey001
  2. Application shared key: SomeAppSharedKey001
  3. Parameters of the request we want to send (query string): appKey=SomeAppKey001&bgColor=ff660033&fgColor=993333bb&width=2048&height=1024&[email protected],13.851300&[email protected],35.857268&[email protected],101.617261
  4. Sort all parameters (param_name=param_value) alphabetically and concatenate them
  5. Append the application shared key
  6. Calculate SHA1 of such string: SHA1(appKey=SomeAppKey001bgColor=ff660033fgColor=993333bb[email protected],101.617261[email protected],13.851300[email protected],35.857268height=1024width=2048SomeAppSharedKey001)

Examples: