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	Public user ID.		Each user can check their public 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 public ID. For example in the following permalink https://www.mytravelmap.xyz/u/123e4567-e89b-12d3-a456-426614174000 the 123e4567-e89b-12d3-a456-426614174000 is the user's public 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

Examples:

2) Get user's countries

Endpoint:	GET countries.json
Resource URL:	http://www.mytravelmap.xyz/api/v1/countries.json
Response format:	JSON response with the user's countries grouped by WorldMap.Status: BORN, LIVED, VISITED, WANT_TO_VISIT. Each country contains its ISO code and localized name.

Parameters

Name	Required	Description	Default value	Example
appKey	Yes	Application identifier		JKUmj2fjJMgOQs3Y
userId	Yes	Public user ID.		Each user can check their public 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 public ID. For example in the following permalink https://www.mytravelmap.xyz/u/123e4567-e89b-12d3-a456-426614174000 the 123e4567-e89b-12d3-a456-426614174000 is the user's public ID.
locale	No	Language used for country names. Supported locale values are the same as listed for pinLabelLocale in the world map service.	en	cs
sig	Yes (when using your app key) No (when using testing app key)	Request signature which is created for security reasons		bf72dbe5fb6f588ff3df6fcb23587b220c204da3

Example response

	
{
  "status": "OK",
  "countries": {
    "BORN": [
      {
        "isoCode": "CZ",
        "name": "Czech Republic"
      }
    ],
    "LIVED": [
      {
        "isoCode": "GB",
        "name": "United Kingdom"
      }
    ],
    "VISITED": [
      {
        "isoCode": "FR",
        "name": "France"
      },
      {
        "isoCode": "IT",
        "name": "Italy"
      }
    ],
    "WANT_TO_VISIT": [
      {
        "isoCode": "JP",
        "name": "Japan"
      }
    ]
  }
}

Creating a Request Signature

The parameter sig equals SHA1 from the concatenation of the following strings:

Arrange all request parameters (parameter_name=parameter_value) alphabetically in ascending order. (Except the 'sig' parameter which value we are calculating right now)
APP_SHARED_SECRET

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:

Application key: SomeAppKey001
Application shared key: SomeAppSharedKey001
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
Sort all parameters (param_name=param_value) alphabetically and concatenate them
Append the application shared key
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)