Add place

Close

API Documentation

w00t? Yeah, you can now read Hitchwiki Maps database trough an open API! It's the same API we use at our JavaScript frontend for web and mobile.

API call base URL: http://hitchwiki.org/maps/api/

API call base URL for demo purpose: http://hitchwiki.org/devmaps/api/
Use this when you want to test your program, since it uses a different database and changes won't go visible to the actual website.

List of API-calls

Place info

/api/?place=[ID]
Get all info about place by ID.
JSON Example:
{
	"id":"355",
	"lat":"51.2029594207479",
	"lon":"4.38469022512436",
	"elevation":"7",
	"rating":"5",
	"rating_count":"1",
	"location":
	{
		"city":"Antwerp",
		"country":
		{
			"iso":"BE",
			"name":"Belgium"
		},
		"continent":
		{
			"code":"EU",
			"name":"Europe"
		}
	},
	"user":
	{
		"id":"10",
		"name":"Joe Doe"
	},
	"link":"http:\/\/maps.hitchwiki.org\/?place=355",
	"datetime":"2010-07-29 15:12:20",
	"description":
	{
		"en_UK":
		{
			"datetime":"2011-01-31 23:41:15",
			"fk_user":"12345",
			"description":"Lorem ipsum dolor sit amet.",
			"versions":"2"
		},
		"lt_LT":
		{
			"datetime":"2010-12-22 21:11:12",
			"fk_user":"12355",
			"description":"Loremė ipsumius dolor šites amet.",
			"versions":"1"
		},
	},
	"comments":
	{[
		{
			"id":"1",
			"comment":"Lorem ipsum dolor sit amet!",
			"datetime":"2010-07-30 14:45:57",
			"user":
			{
				"nick":"Joe Doe"
			}
		},
		{
			"id":"2",
			"comment":"Lorem ipsum test.",
			"datetime":"2010-07-30 15:12:20",
			"user":
			{
				"id":"1",
				"name":"Joe Doe"
			}
		}
	]},
	"comments_count":2
}


/api/?place=[ID]&dot
Get very basic info about place by ID by adding a dot to the query. Just what you might need to draw a point to the map.
JSON Example:
{
	"id":"355",
	"lat":"51.2029594207479",
	"lon":"4.38469022512436",
	"rating":"0"
}


List places from area

/api/?bounds=59.375129767984,64.208716083434,22.544799804826,35.190063476196
JSON Example:
[
	{
		"id":"957",
		"lat":"61.4893999989479",
		"lon":"23.7795531749725",
		"rating":"2"
	},
	{
		"id":"1591",
		"lat":"61.1811048903562",
		"lon":"23.8870024681091",
		"rating":"1"
	},
	...

]


List places by city

/api/?city=[CITYNAME IN ENGLISH]
See an example from "List places from area"-section.

List places by country

/api/?country=[COUNTRY ISO CODE]
Get all places from a country by country ISO-code. See the list of codes.

See an example from "List places from area"-section.

List places by continent

/api/?continent=[CONTINENT CODE]
  • AS: Asia
  • AF: Africa
  • NA: North America
  • SA: South America
  • AN: Antarctica
  • EU: Europe
  • OC: Australia and Oceania
See an example from "List places from area"-section.

List of continents

/api/?continents
  • Short code
    • AS: Asia
    • AF: Africa
    • NA: North America
    • SA: South America
    • AN: Antarctica
    • EU: Europe
    • OC: Australia and Oceania
  • Name
  • Places count
JSON Example:
{
	"AS":
	{
		"name":"Asia",
		"code":"AS",
		"places":"89"
	},
	"AF":
	{
		"name":"Africa",
		"code":"AF",
		"places":"19"
	},
	...
}


List of countries

List only countries with places:
/api/?countries

List all countries, also with 0 places:
/api/?countries=all

Get also country coordinates with coordinates-variable:
/api/?countries&coordinates
  • ISO short code
  • Name
  • Places count
  • Latitude (not by default)
  • Longitude (not by default)
JSON Example with coordinates:
{
	"Germany":
	{
		"iso":"DE",
		"name":"Germany",
		"places":"662"
	},
	"France":
	{
		"iso":"FR",
		"name":"France",
		"places":"423"
	},
	...
}


List of languages

Get a list of available languages. /api/?languages
  • ISO code
  • Language name in requested language (default en_UK)
  • "In Language" in original language
JSON Example:
{
	"en_UK":
	{
		"code":"en_UK",
		"name":"English",
		"name_original":"In English"
	},
	"de_DE":
	{
		"code":"de_DE",
		"name":"German",
		"name_original":"Auf Deutsch"
	},
	...
}


Test API

To test if you can connect to the API, just ask /api/?ping

JSON Example:
{"ping":"pong"}


In case of error

If API produces an error, it returns "error":"true" and possible error description.

JSON Example where calling /api/?place=351 didn't find a place with this ID:
{
	"error":"true",
	"error_description":"Place not found."
}


Custom variables

Variables you can use with all API calls:
  • lang: output countrynames and continents in certain language, available:
    • en_UK: English (default)
    • fi_FI: Finnish
    • de_DE: German
    • nl_NL: Dutch
    • pt_PT: Portuguese
    • ru_RU: Russian
    • ro_RO: Romanian
    • lt_LT: Lithuanian
    • it_IT: Italian
    • zh_CN: Chinese
    • fr_FR: French
    • pl_PL: Polish
    • hu_HU: Hungarian
    • tr_TR: Turkish


  • format: not required. By default API returns a JSON string, but you can ask for: json, kml and string (for testing - it's just human readable rather than computer). NOTICE: KML format not functional yet.

  • download: force to download as a file. If you add content to it, it's used as a filename. Eg. download=filename. Default filename is "places" and ".json/kml/txt" will be added depending on requested format. Valid characters are "a-zA-Z0-9._-" and max 255 of them.

  • who: it's not required, but would be lovely to see who uses our API. You can add unique string like service name, URL or email to this.

  • callback: if you're using JSON format with javascript from your own server, you'll hit browser's cross domain policy. Work around this is to use so called JSONP technique. Add a callback to your API-call and response will be wrapped with function you choose, eg. /api/?ping&callback=demo will produce:
    demo({"ping":"pong"})

    This you can just include to your webpage with <script> tag, since cross domain policy won't apply for it.



Example, download a file "testfile.kml" with a place on it in Finnish: /api/?id=355&format=kml&download=testfile&lang=fi_FI&who=Hitchwiki

License

Creative Commons License

Licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.


Turn JavaScript on from your browser.