log inhelp

View
 

Creating App-Specific Entities

URL | Parameters | Creating a User Entity | Updating a User Entity | Deleting a User Entity | Examples | Creation Query | Creation Response | Deletion Query | Deletion Response

 

In addition to the tens of millions of already defined entities, you can define (and delete, if needed) your own entities. These entities can also be annotated by you, your application, and/or your users. For example, you might want to define entities for publically accessible restrooms in your city and let users annotate each one as to its cleanliness.

 

Similar to GeoAPI's User Views, you create App-Specific entities within your GeoAPI API Key namespace. Any entity you create with a given key can only be accessed by an app using that same key.

 

You can run all of GeoAPI's view methods on your created entities.

 

URL          [Top]

 

http://api.geoapi.com/v1/e/

http://api.geoapi.com/v1/e/<guid>

 

HTTP Methods:

  • POST: Create or Update an entity
  • DELETE: Delete an entity (must include the entity guid in the url)

 

GUID Format:

 

App-Specific Entities have the following GUID format: user-<api-key>-<id>, where <api-key> is your API key and <id> is a unique string within the API key namespace. For example, if your API key is "foo" and you create an entity "bar", its fully qualified url is http://api.geoapi.com/v1/e/user-foo-bar

 

Parameters          [Top]

 

  • apikey:
    • Required.
    • Your application's GeoAPI key.
    • Format: String.
  • pretty:
    • Optional.
    • Enables easier to read prettified JSON in result.
    • Format: Set equal to 1 to enable prettification.
  • jsoncallback:
    • Optional.
    • Return response in JSONP format. JQuery has nice support for JSONP callbacks.
    • Format: JSON prefix string.

 

Creating A User-Entity          [Top]

 

To create a user entity, you either POST to the global GeoAPI entity root url (ex. http://api.geoapi.com/v1/e/) or to the full url of the entity you want to create (ex. http://api.geoapi.com/v1/e/user-demo-someid). If you don't specify a guid (i.e. POST http://api.geoapi.com/v1/e/), GeoAPI creates an entity with an assigned unique guid. If you specify an already existing guid, the new entity data overwrites the existing data.

 

The POST's body must be a valid JSON object, with the following properties:

 

 

Updating A User-Entity          [Top]

 

As noted, posting JSON data to http://api.geoapi.com/v1/e/<guid> overwrites an existing user-entity's data. Which, in effect, is another way of saying it updates the entity's data.

 

Deleting A User-Entity          [Top]

 

To delete a user-entity, make an HTTP DELETE request to that entity's url, for example, http://api.geoapi.com/v1/e/user-demo-someid.

 

Examples          [Top]

 

User entities are also created and read in the Twitter Empire demo.

 

Query          [Top]

 

Create a user-entity called "Golden Gate Park", and define its boundaries with a polygon.

 

HTTP POST Request:

{
"name": "Golden Gate Park",
"geom": {
"type": "Polygon",
"coordinates": [
[
[-122.45498657226562,37.77338331513476],
[-122.51094818115234,37.770940891530486],
[-122.51026153564453,37.76388454792691],
[-122.45361328125,37.76551299467243],
[-122.45498657226562,37.77338331513476]
]
]
}
}

 

to the url:

 

http://geoapi.com/v1/e/user-demo-golden-gate?apikey=demo

 

Response          [Top]

 

{
"query": {
"type": "entity",
"params": {
"guid": "user-demo-golden-gate"
}
},
"result": {
"name": "Golden Gate Park",
"views": ["weather", "foursquare", "twitter", "flickr", "youtube"],
"userviews": [],
"shorturl": "http://geo.am/abcd",
"geom": {
"type": "Polygon",
"coordinates": [[[ - 122.454987, 37.773383], 
[ - 122.510948, 37.770941], 
[ - 122.510262, 37.763885], 
[ - 122.453613, 37.765513], 
[ - 122.454987, 37.773383]]]
},
"type": "user-entity"
}
}

Query          [Top]

 

You delete a user-created entity by making an HTTP DELETE request to it. To delete the user-entity user-demo-golden-gate created by the example above:

 

HTTP DELETE Request to: http://geoapi.com/v1/e/user-demo-golden-gate?apikey=demo

 

Response          [Top]

 

An HTTP 200 message with no content in the response body. 

 

Printable version