For developers API

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
bmp - generates actual image in BMP 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 (sea).
(either 6 hexadecimal RGB or 8 hexadecimal RGBA)
ffffff RGB - c0c0c0
RGBA - c0c0c099
fgColor No Image foreground color (land).
(either 6 hexadecimal RGB or 8 hexadecimal RGBA)
a9a9a9 RGB - c0c0c0
RGBA - c0c0c099
dither No Intentionally applied form of noise. See Wikipedia - Dither no no
yes
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 'rgb$lat,lon!...' or 'rgba$lat,lon!...'
990000$50.361459,13.851300
990000$50.361459,13.851300!32.548774,35.857268
990000$50.361459,13.851300!32.548774,35.857268!3.113924,101.617261
cc7700aa$50.361459,13.851300
cc7700aa$50.361459,13.851300!32.548774,35.857268
cc7700aa$50.361459,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 'rgb$lat,lon!...' or 'rgba$lat,lon!...'

The pins will always be placed in the middle of country which contains the GPS coordinate!
990000$50.361459,13.851300
990000$50.361459,13.851300!32.548774,35.857268
990000$50.361459,13.851300!32.548774,35.857268!3.113924,101.617261
cc7700aa$50.361459,13.851300
cc7700aa$50.361459,13.851300!32.548774,35.857268
cc7700aa$50.361459,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), Amharic (am), Arabic (ar), Armenian (hy), Azerbaijani (az), Bangla (bn), Belarusian (be), 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), Kazakh (kk), Korean (ko), Lao (lo), Latvian (lv), Lithuanian (lt), Malay (ms), Mongolian (mn), Nepali (ne), Norwegian (no), Persian (fa), Polish (pl), Portuguese (pt-BR), Portuguese (pt-PT), Romanian (ro), Russian (ru), Serbian (sr), Slovak (sk), Slovenian (sl), Spanish (es), Swahili (sw), Swedish (sv), Tamil (ta), Thai (th), Turkish (tr), Ukrainian (uk), Urdu (ur), 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
userId No User ID in our system. Each user can check their ID after logging in into our website and by clicking on "Permalink" on the left menu. A popup window will display the user's permalink. The last part of the permalink is the user's ID in our system.
For example in the following permalink https://www.mytravelmap.xyz/u/fb10153329637423541 the fb10153329637423541 is the user's ID.
userColorBorn No Color of the country the user was born in.
(either 6 hexadecimal RGB or 8 hexadecimal RGBA)

This parameter is only used when userId is specified as well.
000000 RGB - c0c0c0
RGBA - c0c0c099
userColorLived No Color of the country the user has lived in.
(either 6 hexadecimal RGB or 8 hexadecimal RGBA)

This parameter is only used when userId is specified as well.
000000 RGB - c0c0c0
RGBA - c0c0c099
userColorVisited No Color of the country the user has visited.
(either 6 hexadecimal RGB or 8 hexadecimal RGBA)

This parameter is only used when userId is specified as well.
000000 RGB - c0c0c0
RGBA - c0c0c099
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&geo=990000$50.361459,13.851300&geo=f2d70c$32.548774,35.857268&geo=403edddd$3.113924,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=993333bbgeo=403edddd$3.113924,101.617261geo=990000$50.361459,13.851300geo=f2d70c$32.548774,35.857268height=1024width=2048SomeAppSharedKey001)

Examples: