Prerequisite

Prior making these api calls, user would need to create an account in KingGaai, and obtain the api key through the develop tab of the profile page.

Methods

createPost

POST https://www.kinggaai.com/api/createPost

This endpoint lets you create a post that will be placed onto the map.

Example payload:

					{
	apiKey: 'apiKeyFromKingGaai',
	title: 'Fly away',
	location: { 
		coordinates: [ 
			[ -120.9375, 38.20365531807151 ],
			[ 137.5897549001843, -23.61129546449346 ]
		], 
		addresses: [ 
			'United States', 
			'Australia' 
		] 
	},
	content: "Let's go somewhere else.",
	language: 'en',
	category: 'travel_airplane',
	status: '',
	eventTime: { 
		from: '2024-02-18T18:00:00.000Z', 
		to: '2024-02-19T12:00:00.000Z' 
	}
}
Mandatory arguments:
  • apiKey : The key obtained through the profile page after login.
  • title: The title of the new post, recommanded to be as short and precise as possible since it will get truncated.
  • content: The content of the new post.
  • category: The category regarding to the new post, it can be any one of the following and it is case sensitive.
    • discussion
    • emergency
    • entertainment
    • food_beverage
    • housing
    • jobs
    • learning
    • news
    • pets
    • shopping
    • sport_exercise
    • travel_airplane
    • travel_car
  • language: The EIDR Language Code of the new post belongs to, it can be any combinations of the following and it is case sensitive.
    • en
    • zh-yue
    • hi
    • ja
    • ko
    • zh-cmn
    • es
  • (location | coordinatesQuery): exclusive arguments (eitherA | eitherB).
    • location: contains coordinates and the addresses of the new post. 
      				{
	"coordinates":[
		[ 
			91, // longitude
			30. // latitude
		],
		[ 
			-91, // longitude
			-30. // latitude
		]
	],    
	"addresses":[
		"placeA",
		"placeB"
	],
}
      • coordinates is an array contains any number from 1 up to 10 of 2 sized arrays that indicates the geolocation.
      • addresses helps to indicate the name of the coordinates provided. It is optional, it can be either null or the array length of it needs to be the same as the coordinates arrays, and the order of the addresses should match the order of the coordinates.
    • coordinatesQuery is used for when the actual cootes of the post is unknown, but it can be queried using a list of known location names. But notice the accuracy of the coordinate query can be low sometimes, it is recommanded to provide coordinates directly if that is known. 
      				{
	"names": list(locations),
	"countryBound": list(countryCodes),
}
      • names: a list of locations name, for example, ["new york empire state building"], or ["Shinjuku City", "Shibuya Sky"].
      • countryBound: a list of ISO 3166-1 alpha-2 country code, for example, ["US", "CA"].
  • status: The status of the new post, it can be any one of the followings:
    • "": empty string, indicate this is a normal post and created by user.
    • "_BOT": a post created by robot, recommanded to use this status when this information is gathered automatically.
    • "_ADS": a post that involves commercial activity, if this post is created for any incomes earning purposes, this post needed to be set as this status.
Optional Arguments:
  • eventTime: The event start and stop time of the event associate with the post. Notice event start and stop time needs to be at most a month from now. 
    				{
	from: '2024-01-01T00:00:00.000+00:00'
	to: '2024-01-01T01:00:00.000+00:00'
}
  • source: The url of the post if there is involves dicussion regarding to another website.
  • amount: If there is s a price associated with the post, the amount would be that, it should be either per event or per month based on common sense.
Returns:
  • HTTP status of 200. The content can be viewed under https://www.kinggaai.com/room?id={id}&lat={lat}&lng={lng}. 
    				{
	id,	    // id associated with the post.
	coordinates: [
		0,	// longitude
		0	// latitude
	],
}
  • HTTP status of 400, invalid one or more arguments, the return message should indicate the invalid fields.
  • HTTP status of 401, unable to verify apiKey, make sure your api key is correct or create an new user if needed.
  • HTTP status of 409, data conflict is found, make sure you only provide either location or coordinatesQuery, not both or not neither.
  • HTTP status of 500, unknown reason, contact us for more information.