log inhelp

View
 

User Views

Writing Data To A User View | URL | Parameters | Response Properties

Reading Data From A User View | URL | Parameters | Response Properties

Indexing With The options Method

 

User Views allow developers and users to annotate any GeoAPI entity with their own data. This private data is kept in its own namespace which has a one-to-one correspondence with an application's GeoAPI key. Each namespace can contain multiple distinct views.

 

For example, let's say you have an app called ScavengerHunt. When a user starts a new hunt, the app assigns them a view name, such as TomHunt-1. For that hunt, users will write and read data to and from the TomHunt-1 view in the namespace associated with ScavengerHunt's GeoAPI key. For a different hunt using the ScavengerHunt app, users would write and read data to and from the JessicaHunt-1 view in that same namespace. Even if both hunts annotated the Ritual Roasters entity, their annotations would be found in different views in the ScavengerHunt namespace.

 

But let's say there's also a competing app called TreasureHunt. Its views are stored in a different namespace from the ScavengerHunt views, based on the apps' respective GeoAPI keys. So even if both ScavengerHunt and TreasureHunt have a view named TomHunt-1, each TomHunt-1 view will be in a separate namespace. ScavengerHunt users will write and read data to/from its TomHunt-1 view, and TreasureHunt users will write and read data to/from its TomHunt-1 view with no overlap between the two applications and their respective views. Neither app's users will be able to see or change the data in the other app's views, unless the apps share a single GeoAPI key.

 

To summarize, each user view is uniquely specified by the combination of its name and its application's GeoAPI key.

 

To write data to a user view, you POST information in JSON format to any entity and specify the name of the view you want the data associated with.

 

To read data from a user view, you just run a similar method to a regular, non-user, view such as listing.

 

userview is used in the Location Check-Ins and Twitter Empire demos.

 

Writing Data To A User View          [Top]

 

You can write data to a user view using either a POST or a GET:

 

  • POST: The POST's body is the data.
  • GET: The value of the set-content parameter is the data.

 

The data must be in JSON format. If the JSON-formatted data doesn't validate, an error is returned. 

 

User views are append only. You cannot delete or change the content of any data you add to a user view. Each new entry is timestamped with its creation time. When you use MQL Search, you can filter results for specific dates or date ranges.

 

For example, if you have a custom view called monsters-in-town and you want to associate information about a monster in Ritual Roasters, you would POST to

 

http://api.geoapi.com/v1/e/ritual-coffee-roasters-san-francisco-ca-94110/userview/monsters-in-town?apikey=demo

 

with some data - for example:

 

{"name": "Zombie Fixie Rider",
 "creator": "hipsternaut",
 "eats": ["nerds", "baristas"]
}

You would have:

 {
 "query": {
   "params": {
     "userview": "bar",
     "guid": "ritual-coffee-roasters-san-francisco-ca-94110"
   },
   "type": "entity-view"
 },
 "result": {
   "entries": [
     {
       "date": "2009-11-12T18:55:26Z",
       "data": {

                 "name": "Zombie Fixie Rider",
                 "creator": "hipsternaut"
                 "eats": ["nerds", "baristas"]
               },
       "id": "QPyouiLp"      }
   ]
  }
}

 

URL          [Top]

 

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

 

Parameters          [Top]

 

  • guid:
    • Required.
    • Any GeoAPI entity's guid. Can be of any entity type.
    • Format: String.
  • viewname:
    • Required.
    • Name of any view associated with this app's GeoAPI key.
    • Format: String.
  • apikey:
    • Required.
    • Your application's GeoAPI key.
    • Format: String.
  • set-content:
    • Required for writing data when using GET,  not needed when using POST.
    • JSON-formatted data that's written to the specified user view.
    • Format: JSON-formatted string.
  • pretty:
    • Optional.
    • Enables prettified JSON in result (easier for people to read)
    • 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.

 

Response Properties          [Top]

 

  • date: A string, the UTC time stamp when this data was added to the view.
  • data: A JSON object, the property-value pairs content of this data entry.
  • id: A string, a unique id assigned to this data by GeoAPI.

 

Reading Data From A User View          [Top]

 

To read data from a user view, you just send a request that specifies what guid and what user view to return data from. The result looks like: 

 

 {
 "query": {
   "params": {
     "userview": <viewname>,
     "guid": <entity guid>
   },
   "type": "entity-view"
 },
 "result": {
   "entries": [
     {
       "date": <date>,
       "data": <POST'ed data>,
       "id": <entry id>
       },       ...
   ]
 }

}

 

URL          [Top]

 

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

 

Note: Remember, the user view is uniquely specified by the combination of the viewname and apikey parameters.

 

Parameters          [Top]

 

  • guid:
    • Required.
    • Any GeoAPI entity's guid. Can be of any entity type.
    • Format: String.
  • viewname:
    • Required.
    • Name of any view associated with this app's GeoAPI key.
    • Format: String.
  • apikey:
    • Required.
    • Your application's GeoAPI key.
    • Format: String.
  • pretty:
    • Optional.
    • Enables prettified JSON in result (easier for people to read)
    • 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.

 

Response Properties          [Top]

 

  • date: A string, the UTC time stamp when this data was added to the view.
  • data: A JSON object, the property-value pairs content of this data entry.
  • id: A string, a unique id assigned to this data by GeoAPI.

 

 

Indexing With The options Method          [Top]

 

Developers can request that user view fields be indexed by calling an options method. You can then write MQL queries that constrain on that field. For example, to index field one in the bar user view as a string (values can be string, integer or float), you would call:

 

curl --data-binary '{"fields": {"one": {"index-as": "string"}}}'

"http://api.geoapi.com/v1/options/userview/bar?apikey=demo"

 

If you then write data to the bar view with:

 

curl --data-binary '{"one": "some-value", "two": "not-indexed"}'

"http://api.geoapi.com/v1/e/ritual-coffee-roasters-san-francisco-ca-94110/userview/bar?apikey=demo"

 

And then make an MQL Search query to http://api.geoapi.com/v1/e/ritual-coffee-roasters-san-francisco-ca-94110/userview/bar with the q parameter as:

{

"lat": 37.75629

"lon": -122.4213

"radius": "0.2km"

"entity": [{

   "type": "business"

   "userview.bar": {

     "entries": [{

       "data": {

         "one": "some-value"

       }

     }]

   }

}]

}

 

You would receive the response:

 

{

"lat": 37.75629,

"lon": -122.4213,

"radius": "0.2km",

"entity": [

   {

     "userview.bar": {

       "entries": [

         {

           "data": {

             "one": "some-value"

           }

         },

         {

           "data": {

             "one": "some-value"

           }

         }

       ]

     },

     "type": "business"

   }

]

}

 

 

 

Printable version