Post

Documentation

In on March 27, 2011 by admin

Documentation for all geo data and events data in happng.com. To get a developers key email us at api@happng.com.

Reference on how to use the REST XML API:

  • categories – Returns all the available categories
  • country_code – User sends the country name and it will return the country code
  • region_code – User sends the region name/state name and it will return the region code
  • zip_to_geo – User sends the zipcode and it will return all matches
  • city_to_geo – User sends city information such as city name, country, region/state name and it will return all matches
  • ip_to_geo – User sends an IP and we return all geo matches to the IP address
  • spatial_geo – User sends latitude and longitude along with the distance and unit type (miles, nautical miles, or kilometers). API will return all matches within the spatial radius provided
  • search – Search for events based on geo and categories

 

categories

Returns all the available categories
Variables:

  • key – Your application key
  • method – categories

http://www.happng.com/api.php?key=…&method=categories

	<?xml version="1.0" encoding="UTF-8"?>
	<api xmlns:p="http://www.happng.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<summary>
			<request_date>20110328142736</request_date>
			<request_type>categories</request_type>
			<request_speed>0.0006 sec</request_speed>
		</summary>
		<response>
			<user_session_key></user_session_key>
			<user_valid>1</user_valid>
			<user_display></user_display>
			<section>
				<section_description>Available Categories</section_description>
				<items>
					<item>
						<events_category_id>10</events_category_id>
						<events_category_name>Comedy</events_category_name>
						<events_category_description>Stand-up%2C%20improv%2C%20comic%20theatre</events_category_description>
						<events_category_hash>%23Comedy</events_category_hash>
					</item>
					.
					.
					.
				</items>
			</section>
		</response>
	</api>

 

country_code

User sends the country name and it will return the country code
Variables:

  • key – Your application key
  • method – country_code
  • country – Country name

http://www.happng.com/api.php?key=…&method=country_code&country=United%20States

	<?xml version="1.0" encoding="UTF-8"?>
	<api xmlns:p="http://www.happng.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<summary>
			<request_date>20110328162612</request_date>
			<request_type>country_code</request_type>
			<request_speed>0.0237 sec</request_speed>
		</summary>
		<response>
			<user_session_key></user_session_key>
			<user_valid>1</user_valid>
			<user_display></user_display>
			<section>
				<section_description>Results based on Country United States</section_description>
				<item>
						<country_code>US</country_code>
				</item>
			</section>
		</response>
	</api>

 

region_code

User sends the region name/state name and it will return the region code
Variables:

  • key – Your application key
  • method – region_code
  • region – Region name

http://www.happng.com/api.php?key=…&method=region_code&region=Georgia

	<?xml version="1.0" encoding="UTF-8"?>
	<api xmlns:p="http://www.happng.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<summary>
			<request_date>20110328164427</request_date>
			<request_type>region_code</request_type>
			<request_speed>0.0149 sec</request_speed>
		</summary>
		<response>
			<user_session_key></user_session_key>
			<user_valid>1</user_valid>
			<user_display></user_display>
			<section>
				<section_description>Results based on Region Georgia</section_description>
				<item>
						<region_code>GA</region_code>
				</item>
			</section>
		</response>
	</api>

 

zip_to_geo

User sends the zipcode and it will return all matches
Variables:

  • key – Your application key
  • method – zip_to_geo
  • zipcode – Zipcode or Postal code

http://www.happng.com/api.php?key=…&method=zip_to_geo&zipcode=30308

	<?xml version="1.0" encoding="UTF-8"?>
	<api xmlns:p="http://www.happng.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<summary>
			<request_date>20110328165108</request_date>
			<request_type>zip_to_geo</request_type>
			<request_speed>0.012 sec</request_speed>
		</summary>
		<response>
			<user_session_key></user_session_key>
			<user_valid>1</user_valid>
			<user_display></user_display>
			<section>
				<section_description>Results based on Zipcode 30308</section_description>
				<item>
						<country_code>US</country_code>
						<country_name>United%20States</country_name>
						<region_code>GA</region_code>
						<region_name>Georgia</region_name>
						<city>Atlanta</city>
						<zipcode>30308</zipcode>
						<latitude>33.7719</latitude>
						<longitude>-84.3771</longitude>
				</item>
			</section>
		</response>
	</api>

 

city_to_geo

User sends city information such as city name, country, region/state name and it will return all matches
Variables:

  • key – Your application key
  • method – city_to_geo
  • city – City name
  • region – Region name
  • country – Country name

http://www.happng.com/api.php?key=…&method=city_to_geo&city=Atlanta

	<?xml version="1.0" encoding="UTF-8"?>
	<api xmlns:p="http://www.happng.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<summary>
			<request_date>20110328165518</request_date>
			<request_type>city_to_geo</request_type>
			<request_speed>0.0104 sec</request_speed>
		</summary>
		<response>
			<user_session_key></user_session_key>
			<user_valid>1</user_valid>
			<user_display></user_display>
			<section>
				<section_description>Results based on City Atlanta + Region  + Country </section_description>
				<item>
						<country_code>US</country_code>
						<country_name>United%20States</country_name>
						<region_code>GA</region_code>
						<region_name>Georgia</region_name>
						<city>Atlanta</city>
						<zipcode>30308</zipcode>
						<latitude>33.7719</latitude>
						<longitude>-84.3771</longitude>
				</item>
				<item>
						<country_code>US</country_code>
						<country_name>United%20States</country_name>
						<region_code>IN</region_code>
						<region_name>Indiana</region_name>
						<city>Atlanta</city>
						<zipcode>46031</zipcode>
						<latitude>40.2043</latitude>
						<longitude>-86.0237</longitude>
				</item>
				<item>
						<country_code>US</country_code>
						<country_name>United%20States</country_name>
						<region_code>TX</region_code>
						<region_name>Texas</region_name>
						<city>Atlanta</city>
						<zipcode>75551</zipcode>
						<latitude>33.127</latitude>
						<longitude>-94.1992</longitude>
				</item>
			</section>
		</response>
	</api>

 

http://www.happng.com/api.php?key=…&method=city_to_geo&city=Atlanta&country=United States

	<?xml version="1.0" encoding="UTF-8"?>
	<api xmlns:p="http://www.happng.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<summary>
			<request_date>20110328165652</request_date>
			<request_type>city_to_geo</request_type>
			<request_speed>0.0009 sec</request_speed>
		</summary>
		<response>
			<user_session_key></user_session_key>
			<user_valid>1</user_valid>
			<user_display></user_display>
			<section>
				<section_description>Results based on City Atlanta + Region  + Country United States</section_description>
				<item>
						<country_code>US</country_code>
						<country_name>United%20States</country_name>
						<region_code>GA</region_code>
						<region_name>Georgia</region_name>
						<city>Atlanta</city>
						<zipcode>30308</zipcode>
						<latitude>33.7719</latitude>
						<longitude>-84.3771</longitude>
				</item>
				<item>
						<country_code>US</country_code>
						<country_name>United%20States</country_name>
						<region_code>IN</region_code>
						<region_name>Indiana</region_name>
						<city>Atlanta</city>
						<zipcode>46031</zipcode>
						<latitude>40.2043</latitude>
						<longitude>-86.0237</longitude>
				</item>
				<item>
						<country_code>US</country_code>
						<country_name>United%20States</country_name>
						<region_code>TX</region_code>
						<region_name>Texas</region_name>
						<city>Atlanta</city>
						<zipcode>75551</zipcode>
						<latitude>33.127</latitude>
						<longitude>-94.1992</longitude>
				</item>
			</section>
		</response>
	</api>

 

http://www.happng.com/api.php?key=…&method=city_to_geo&city=Atlanta&country=United States&region=Georgia

	<?xml version="1.0" encoding="UTF-8"?>
	<api xmlns:p="http://www.happng.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<summary>
			<request_date>20110328165816</request_date>
			<request_type>city_to_geo</request_type>
			<request_speed>0.0008 sec</request_speed>
		</summary>
		<response>
			<user_session_key></user_session_key>
			<user_valid>1</user_valid>
			<user_display></user_display>
			<section>
				<section_description>Results based on City Atlanta + Region Georgia + Country United States</section_description>
				<item>
						<country_code>US</country_code>
						<country_name>United%20States</country_name>
						<region_code>GA</region_code>
						<region_name>Georgia</region_name>
						<city>Atlanta</city>
						<zipcode>30308</zipcode>
						<latitude>33.7719</latitude>
						<longitude>-84.3771</longitude>
				</item>
			</section>
		</response>
	</api>

 

ip_to_geo

User sends an IP and we return all geo matches to the IP address
Variables:

  • key – Your application key
  • method – ip_to_geo
  • ip – IP to analyze

http://www.happng.com/api.php?key=…&method=ip_to_geo&ip=98.242.71.68

	<?xml version="1.0" encoding="UTF-8"?>
	<api xmlns:p="http://www.happng.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<summary>
			<request_date>20110328170108</request_date>
			<request_type>ip_to_geo</request_type>
			<request_speed>0.0011 sec</request_speed>
		</summary>
		<response>
			<user_session_key></user_session_key>
			<user_valid>1</user_valid>
			<user_display></user_display>
			<section>
				<section_description>Results based on IP 98.242.71.68</section_description>
				<item>
					<country_code>US</country_code>
					<country_name>United%20States</country_name>
					<region_code>GA</region_code>
					<region_name>Georgia</region_name>
					<city>Atlanta</city>
					<zipcode></zipcode>
					<latitude>33.8004</latitude>
					<longitude>-84.3865</longitude>
				</item>
			</section>
		</response>
	</api>

 

spatial_geo

User sends latitude and longitude along with the distance and unit type (miles, nautical miles, or kilometers). API will return all matches within the spatial radius provided
Variables:

  • key – Your application key
  • method – spatial_geo
  • latitude – Latitude value
  • longitude – Longitude value
  • distance – Spatial/Radius to cover based on the provided latitude and longitude *default value is 10*
  • unit – For miles (m), Nautical miles (n), Kilometers (k) *default is Kilometers*

http://www.happng.com/api.php?key=…&method=spatial_geo&latitude=33.8004&longitude=-84.3865&distance=100&unit=m

	<?xml version="1.0" encoding="UTF-8"?>
	<api xmlns:p="http://www.happng.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<summary>
			<request_date>20110328171025</request_date>
			<request_type>spatial_geo</request_type>
			<request_speed>0.0086 sec</request_speed>
		</summary>
		<response>
			<user_session_key></user_session_key>
			<user_valid>1</user_valid>
			<user_display></user_display>
			<section>
				<section_description>Results based on Coordinates 33.8004 / -84.3865</section_description>
				<item>
						<country_code>US</country_code>
						<country_name>United%20States</country_name>
						<region_code>GA</region_code>
						<region_name>Georgia</region_name>
						<city>Atlanta</city>
						<zipcode>30308</zipcode>
						<latitude>33.7719</latitude>
						<longitude>-84.3771</longitude>
				</item>
				.
				.
				.
			</section>
		</response>
	</api>

 

search

Search for events based on geo and categories
Variables:

  • key – Your application key
  • method – spatial_geo
  • latitude – Set geo based on latitude value
  • longitude – Set geo based on longitude value
  • distance – Spatial/Radius to cover based on the provided latitude and longitude *default value is 10*
  • unit – For miles (m), Nautical miles (n), Kilometers (k) *default is Kilometers*
  • category_ids – Limit results to a particular category. Use commas for multiple categories
  • ip – Set geo based on IP
  • venue_id – Limit results to a particular venue id
  • term – Keywords to search for

http://www.happng.com/api.php?key=…&method=search&latitude=33&longitude=-84&term=music

	<?xml version="1.0" encoding="UTF-8"?>
	<api xmlns:p="http://www.happng.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<summary>
			<request_date>20110328180314</request_date>
			<request_type>search</request_type>
			<request_speed>0.0224 sec</request_speed>
		</summary>
		<response>
			<user_session_key></user_session_key>
			<user_valid>1</user_valid>
			<user_display></user_display>
			<section>
				<section_description>Results based on Search Patterns</section_description>
				<item>
						<events_archive_id>169922</events_archive_id>
						<events_geo_id>16</events_geo_id>
						<events_archive_source>eventful</events_archive_source>
						<events_archive_title>Uncle%2520Sugar</events_archive_title>
						<events_archive_artists></events_archive_artists>
						<events_archive_headline>Uncle%2520Sugar</events_archive_headline>
						<events_venues_id>32854</events_venues_id>
						<events_archive_description>%2520%253Cp%253E%253Cp%253EUncle%2520Sugar%2520is%2520a%2520blues%252Frock%2520band%2520based%2520in%2520the%2520Nashville%252C%2520Tennessee%2520area.%2520They%2520play%2520the%2520music%2520of%2520Jimi%2520Hendrix%252C%2520Stevie%2520Ray%2520Vaughan%252C%2520Eric%2520Clapton%252FCream%252C%2520ZZ%2520Top%2520and%2520others.%253C%252Fp%253E%253C%252Fp%253E</events_archive_description>
						<events_archive_image>http%3A%2F%2Fstatic.eventful.com%2Fimages%2Fmedium%2FI0-001%2F002%2F660%2F597-4.jpeg</events_archive_image>
						<events_archive_source_url>http%3A%2F%2Feventful.com%2Fatlanta%2Fevents%2Funcle-sugar-%2FE0-001-027343611-4</events_archive_source_url>
						<events_archive_website></events_archive_website>
						<events_archive_tags></events_archive_tags>
						<events_archive_tickets_url></events_archive_tickets_url>
						<events_archive_source_reviews>0</events_archive_source_reviews>
						<events_archive_datetime_start>2011-01-09%2000%3A00%3A00</events_archive_datetime_start>
						<events_archive_tickets_free>0</events_archive_tickets_free>
						<events_archive_tickets_price></events_archive_tickets_price>
						<events_category_id>1</events_category_id>
				</item>
				<item>
						<events_archive_id>43209</events_archive_id>
						<events_geo_id>16</events_geo_id>
						<events_archive_source>last.fm</events_archive_source>
						<events_archive_title>Eric%2520Dodd</events_archive_title>
						<events_archive_artists>Eric%2520Dodd%252C%2520David%2520Bell</events_archive_artists>
						<events_archive_headline>Eric%2520Dodd</events_archive_headline>
						<events_venues_id>8270</events_venues_id>
						<events_archive_description>%253Cdiv%2520class%253D%2522bbcode%2522%253E%253Ca%2520href%253D%2522http%253A%252F%252Fwww.last.fm%252Fmusic%252FEric%252BDodd%252BBand%2522%2520class%253D%2522bbcode_artist%2522%253EEric%2520Dodd%2520Band%253C%252Fa%253E%253C%252Fdiv%253E</events_archive_description>
						<events_archive_image></events_archive_image>
						<events_archive_source_url>http%3A%2F%2Fwww.last.fm%2Fevent%2F1877358%2BEric%2BDodd</events_archive_source_url>
						<events_archive_website>http%3A%2F%2Fwww.eddiesattic.com%2F</events_archive_website>
						<events_archive_tags>library%2520music%252C%2520library%252C%2520instrumental%252C%2520quik%2520wanted%252C%2520effects%252C%2520classical</events_archive_tags>
						<events_archive_tickets_url></events_archive_tickets_url>
						<events_archive_source_reviews>0</events_archive_source_reviews>
						<events_archive_datetime_start>2011-03-23%2022%3A00%3A00</events_archive_datetime_start>
						<events_archive_tickets_free>0</events_archive_tickets_free>
						<events_archive_tickets_price></events_archive_tickets_price>
						<events_category_id>1</events_category_id>
				</item>
				.
				.
				.

			</section>
		</response>
	</api>

Leave a Comment