Using the Datasource API requires the following:
GET,PUT, POST and DELETE requestsThe following sections describe these concepts in detail.
Each Datasource is associated with an ACL list of Google Accounts. Each list contains rolls for reading and writing data to the resource. The Default Site ACL allows all authenticated users to read and only admins to write. An ACL can also be set to allow anonymous access (no Google Account) but in most cases you should be tracking who is writing to your Cloud.
You can authenticate using either of two approaches:
ClientLogin authentication uses more traditional username/password requests
to authenticate an application. Typically, this authentication scheme is useful
for standalone, single-user clients (such as a desktop application). ClientLogin
is also useful for testing purposes. The ClientLogin scheme generates an
authentication token so that future actions can reference the token rather
than require further username/password authentications. Additionally,
ClientLogin authentication can be extended to use CAPTCHAs™ or other
enhancements.
To request an authentication token using the ClientLogin mechanism, send a
secure HTTP (HTTPS) POST request to the ClientLogin URL:
https://www.google.com/accounts/ClientLogin
The POST body must be constructed as a form post with default
encoding application/x-www-form-urlencoded. The body of the POST
request should specify the set of query parameters:
GOOGLE;
if you want to support Google Apps for Your Domain users, use
HOSTED_OR_GOOGLE.ah). (For other service
names, see the
service name list.)Upon successful authentication, the server returns an HTTP 200 OK
status code, plus three alphanumeric codes in the body of the response:
SID, LSID, and Auth. The Auth
value contains the authorization token that you'll use to authenticate
to the Maps Data API on subsequent maps-feed requests. (You can ignore the
SID and LSID values.)
Since all requests to private map feeds require authentication you must set
an Authorization header in all
subsequent interactions with the Datasource API, using the following format:
Cookie: ACSID=yourAuthToken
For more information about ClientLogin authentication, including sample
requests and responses, see the
Authentication for Installed
Applications documentation.
You can log directly to your Cloud instance using your Google Account without having to use the ClientLogin authentication described above. When you use the proxy login, your Cloud instance calls the appropriate Google ClientLogin url in the background and returns an opaque token that you can use on your urls. Your Google username and password are not stored and the Proxy must be used via secure https. The token will timeout based on the timespan the administator has set (the default value is one day)
Google's LoginClient is the preferred method for obtaining access to your Cloud but Proxy is a good alternative when subsequent client requests cannot set the authorization header. For instance, Google Earth KML NetworkLinks will not set any custom headers so secure access to dynamic KML resources can be accomplished by appending the proxy token to the urls (http://anyurl?token=tokenFromProxy)
In all of the following examples, the Google ClientLogon ACSID cookie header is used but you could change all of them to use the proxy login token inthe url iteself instead.
https://yourInstance.appspot.com/services/getToken
The POST body must be constructed as a form post with default
encoding application/x-www-form-urlencoded. The body of the POST
request should specify the set of query parameters:
username|password.Usage Example: GET http://yourInstance.appspot.com/a2e/data/datasources/dsName/search?q=Red&token=tokenFromProxy
coming soon...
The Datasource API allows users to create and edit individual datasources using simple HTTP requests given the proper credentials. A Datasource is a collection of vector features that have a common set of attribute fields and usually a common geometry type. It can be searched using both spatial and attribute based parameters (seperately or in combination). It also allows for feature level editing (insert, update, delete) with edit feeds and edit notifications
Geometry - The default format for working with Feature geometry is GeoJson
Field Properties - A collection of name/value pairs for each feature in your datasource. There can be any number of fields for each datasource however, performance (indexing, feature serialization) is directly affected by field count. If a Domain is present on a field, the value of that field in incoming inserts and updates will be validated. If the new value does not match the domain, the update does not occur and a error code is returned.
Red, Blue, Yellow)1 to 100)Get a List of All Datasources
GET http://yourInstance.appspot.com/a2e/data/datasources?f=json&acl=true Cookie: ACSID=yourAuthToken
Response:
{
"datasources": [
{
"acl": {
"admin": false,
"read": true,
"write": true
},
"alias": "",
"copyright": "",
"count": 0,
"description": "",
"features": 0,
"fields": [
{
"alias": "",
"domain":
{
"type": "Range",
"values": [1,100]
},
"name": "SomeField",
"type": "Integer"
},
{
"alias": "",
"domain":
{
"type": "Value",
"values": ["Red", "Blue", "Yellow"]
},
"name": "AnotherField",
"type": "String"
}
],
"geometryType": "Polygon",
"name": "Parcels"
}
]
}
Get Datasource - Retrieve information about a single datasource. Optionally retrieve ACL information for the current user
GET http://yourInstance.appspot.com/a2e/data/datasources/dsName?f=json&acl=true Cookie: ACSID=yourAuthToken
Response:
{
"acl": {
"admin": false,
"read": true,
"write": true
},
"alias": "",
"copyright": "",
"count": 0,
"description": "",
"features": 0,
"fields": [
{
"alias": "",
"domain": [],
"name": "SomeField",
"type": "Integer"
},
{
"alias": "",
"domain": [],
"name": "AnotherField",
"type": "String"
}
],
"geometryType": "Polygon",
"name": "Parcels"
}
Add Datasource - Create a new datasource, a unique name and geomtry type must be supplied. A fields collections and other options can also be sent in the body of the request. If the values in the body are not correctly formatted, the entire operation is cancelled and the datasource is not created.
PUT http://yourInstance.appspot.com/a2e/data/datasources?id=newDS&geometry=Point
Cookie: ACSID=yourAuthToken
Body:
{
"description":"some descriptive text",
"copyright":"some copyright text",
"displayField":"",
"fields":[
{
"name": "fieldName",
"alias": "",
"type": "String",
"default": "Red",
"domain":
{
"type": "Value",
"values": ["Red", "Blue", "Yellow"]
}
}, {
"name": "numericField",
"alias": "",
"type": "Integer",
"default": 0,
"domain":
{
"type": "Range",
"values": [0, 100]
}
}
]
}
Response: 201
{
"status": 201,
"message": "Datasource 'newDS' created",
"result":
{
"count": 0,
"name": "newDS",
"copyright": "",
"displayField":"",
"fields": [...],
"alias": "newDS",
"geometryType": "Point",
"features": 0,
"description": ""
}
}
Errors:
401 - Forbidden
409 - Datasource already exists
400 - Invalid parameter
Update Datasource - You can only update some options for an existing datasource. You cannot update the name or the geometry type. When you add or remove Fields, existing features will not be updated until they are saved again.
POST http://yourInstance.appspot.com/a2e/data/datasources/dsName
Cookie: ACSID=yourAuthToken
Body:
{
"description":"some descriptive text",
"copyright":"some copyright text",
"displayField":"",
"fields":[
{
"name": "fieldName",
"alias": "",
"type": "String",
"default": "Red",
"domain":
{
"type": "Value",
"values": ["Red", "Blue", "Yellow"]
}
}, {
"name": "numericField",
"alias": "",
"type": "Integer",
"default": 0,
"domain":
{
"type": "Range",
"values": [0, 100]
}
}
]
}
Response: 200
{
"status": 200,
"message": "Datasource 'dsName' updated",
"result":
{
"count": 0,
"name": "newDS",
"copyright": "",
"displayField":"",
"fields": [...],
"alias": "newDS",
"geometryType": "Point",
"features": 0,
"description": ""
}
}
Errors:
401 - Forbidden
404 - Datasource doesn't exist
400 - Invalid parameter
Delete Datasource - Deletes a datasource from the datasources colection and returns immediately. Deleting a datasource starts the indexing procedure to remove all data associated with the datasource in the background. Be careful when you run this command.
DELETE http://yourInstance.appspot.com/a2e/data/datasources/dsName Cookie: ACSID=yourAuthToken
Response: 200
{
{"status": 200, "message": "Datasource 'dsName' deleted"}
}
Errors:
401 - Forbidden
404 - Datasource doesn't exist
The Datasource Search API generally follows the OpenSearch Geo draft specification for querying features using attribute or geographic parameters.
| Parameter | Details |
|---|---|
f (default=html) |
Description: The response format of the selected parcels.
Values:
|
| callback |
Description: When the format is json or gjson, this value is appended to the front of the result. This is used primarily with client side APIs that support PJSON
|
| bbox | Description: The Bounding Box used as the search geometry |
| lat | Description: The Latitude value used in the search geometry |
| lon | Description: The Longitude value used in the search geometry |
| ls |
Description: The LineString used as the search geometry. An array of vertices separated by commas in longitude, latitude layout
Format: v1.lon, v1.lat, v2.lon, v2.lat, v3.lon, v3.lat... |
| p |
Description: The Pulygon used as the search geometry. An array of vertices separated by commas in longitude, latitude layout. If the last point in the array does not match the first, the query engine will automatically close the pulygon.
Format: v1.lon, v1.lat, v2.lon, v2.lat, v3.lon, v3.lat... |
| loc |
Description: The Location value used as the search geometry. A location can be one of three values that are parsed and determined by the server.
|
| d |
Description: The offset buffer value (in meters) to use on the search geometry. The value is applied to points, linestrings, polygons and locations values but is not applied to the bbox parameter.
|
| q |
Description: The question used for attribute searches in the form of: AttributeName=Value
|
Example 1: Find Parcel at this Lat/Lng
http://demos-arc2earth.appspot.com/a2e/data/datasources/Westfield_Parcels/search?&lat=40.65102273672606&lon=-74.35689622421187&f=gjson
Example 2: Find Parcels with Owners named "Jones"
http://demos-arc2earth.appspot.com/a2e/data/datasources/Westfield_Parcels/search?q=OWNERNAME="jones*"&f=gjson
Example 3: Find Parcels within 50 meters of Parcel ID: 100
http://demos-arc2earth.appspot.com/a2e/data/datasources/Westfield_Parcels/search?loc=Westfield_Parcels:100&d=50&f=json
Auto Complete is the ability to search for specific features using only a portion of text from one of their fields. The Datasource Search API above allows you to do this using the wildcard character (*) however this service is optimized for running multiple queries at once and returning the results in a format to be used by popular Javascript UI components. You can specify multiple Datasources and the results will include the values that match from each one.
| Parameter | Details |
|---|---|
f (default=json) |
This service only returns json data contaning the following sections.
{
"data": [],
"query": "",
"suggestions": []
}
The values match what is needed by Devbridge's jQuery AutoComplete product however they could be used with other compnents as well |
| query | The partial text value to search on |
| limit (default=10) | The optional value that limits the number of results from each datasource. |
| ds |
A $ delimited list of strings used to define which Datasources and their fields to search on. Each Datasource is encoded into 4 parts, each separated by the | character:
Example: ds=counties|NAME|County:[!NAME],[!STATE]$states|NAME|State:[!NAME]
|
Example: Use AutoComplete across US States, US Counties and US Cities. (run example)
http://test-arc2earth.appspot.com/a2e/data/datasources/autocomplete?limit=10&f=pjson&ds=cities%7CNAME%7CCity%3A+%5B!NAME%5D%2C+%5B!ST_ABBREV%5D%24counties%7CNAME%7CCounty%3A+%5B!NAME%5D%2C+%5B!STATE_NAME%5D%24states%7CSTATE_NAME%7CState%3A+%5B!STATE_NAME%5D&query=Col
{
"data": [
"cities:1062",
"cities:15288",
"cities:19733",
"cities:16573",
"counties:2147",
"counties:1318",
"counties:2597",
"counties:1087",
"counties:1752",
"counties:2435",
"counties:2919",
"counties:2397",
"counties:2098",
"states:31"
],
"query": "Col",
"suggestions": [
"City: Colbert, WA",
"City: Colburn, IN",
"City: Colby, KS",
"City: Colchester, IL",
"County: Colbert, Alabama",
"County: Cole, Missouri",
"County: Coleman, Texas",
"County: Coles, Illinois",
"County: Colfax, New Mexico",
"County: Colleton, South Carolina",
"County: Collier, Florida",
"County: Collin, Texas",
"County: Collingsworth, Texas",
"State: Colorado"
]
}
Compare features from two Datasources using standard spatial overlay operations
The Feature API allows user to create and edit individual vector features in each datasource. A feature consists of unique ID and a single GeoJSON entry. You can add, edit or delete features individually or by using the batch resource to post several edits in a single request. Each feature has a unique string FID (feature id) that is either uploaded with the datasource or is assigned automatically when the feature is inserted.
The format used for editing features is GeoJson.
Get Feature - Use a Feature ID or the exact value of the Display Field for that feature to access it's resource. The format parameter (ex: f=json) will change how the data is returned. Look at the valid values in the Datasource Search parameters above
GET http://yourInstance.appspot.com/a2e/data/datasources/dsName/fid?f=gjson Cookie: ACSID=yourAuthToken
Response: 200
{
"properties": {
"DECNO": "E-138",
"OBJECTID": 100,
"SomeOtherField": ""
},
"geometry": {
"coordinates": [
-73.960883617401123,
40.734117565708246
]
},
"type": "Point",
"id": "100"
}
-or-
{
"properties": {
"FID": 101,
"PARKNUMBER": "X039",
"area": 2729.3323103799999,
"len": 226.386394698
},
"geometry": {
"coordinates": [
[
[
-73.791569843888283,
40.86936725062251
],
[
-73.791487365961075,
40.869295246089123
],
[
-73.791272789239883,
40.86943570556403
],
[
-73.791355267167091,
40.869508217017504
],
[
-73.791569843888283,
40.86936725062251
]
]
]
},
"type": "Polygon",
"id": "101"
}
Errors:
401 - Forbidden
404 - Feature does not exist
Add Feature - Use a valid GeoJson Feature in the request body. If the "id" is blank, a new one will be created and returned automatically. Additionally, if there is an existing attribute field named "id", "fid" or "objectid" it will use that value instead. If you use the value of an existing feature, the feature will not be updated and an error will be returned.
PUT http://yourInstance.appspot.com/a2e/data/datasources/dsName
Cookie: ACSID=yourAuthToken
Body:
{
"properties": {
"DECNO": "E-138",
"SomeOtherField": ""
},
"geometry": {
"coordinates": [
-73.960883617401123,
40.734117565708246
],
"type": "Point"
},
"id":""
}
Response: 201
{
"status": 201,
"message": "Feature '12345_6789' created",
"result":
{
{
"properties": {
"DECNO": "E-138",
"OBJECTID": 100,
"SomeOtherField": ""
},
"geometry": {
"coordinates": [
-73.960883617401123,
40.734117565708246
],
"type": "Point"
},
"id":"12345_6789"
}
}
}
Errors:
401 - Forbidden
409 - Feature already exists
400 - Invalid parameter
Update Feature - Use a valid GeoJson Feature in the body. The "id" in the body and the id in the url must match. If the feature does not exist, the feature will not be added and an error will be returned.
POST http://yourInstance.appspot.com/a2e/data/datasources/dsName/fid
Cookie: ACSID=yourAuthToken
Body:
{
"properties": {
"DECNO": "E-138",
"SomeOtherField": ""
},
"geometry": {
"coordinates": [
-73.960883617401123,
40.734117565708246
],
"type": "Point"
},
"id":"100"
}
Response: 200
{
"status": 200,
"message": "Feature '100' updated",
"result":
{
{
"properties": {
"DECNO": "E-138",
"OBJECTID": 100,
"SomeOtherField": ""
},
"geometry": {
"coordinates": [
-73.960883617401123,
40.734117565708246
],
"type": "Point"
},
"id":"100"
}
}
}
Errors:
401 - Forbidden
404 - Feature does not exists
400 - Invalid parameter
Delete Feature
DELETE http://yourInstance.appspot.com/a2e/data/datasources/dsName/fid Cookie: ACSID=yourAuthToken
Response: 200
{"status": 200, "message": "Feature 'fid' deleted"}
Errors:
401 - Forbidden
404 - Feature doesn't exist
Batch Feature Update - Submit multiple edit operations in a single request. The response contains an exactly ordered list of statuses for each edit operation. Multiple operations on a single feature ID are not guaranteed to be persisted in their original order and thus are not recommended. For valid insert and update Json, see the above topics for individual feature updates.
POST http://yourInstance.appspot.com/a2e/data/datasources/dsName/batch
Cookie: ACSID=yourAuthToken
Body:
{
"items":[
{
"type":"insert",
"value":"...valid insert json..."
},
{
"type":"update",
"value":"...valid update json..."
},
{
"type":"delete",
"value":"fid
}
]
}
Response: 200
{
"items":[
{
"status":201,
"type":"insert",
"result":"...cleaned feature json...",
"id":"12345_67789"
},
{
"status":200,
"type":"update",
"result":"...cleaned feature json...",
"id":"101"
},
{
"status":200,
"type":"delete",
"value":"Feature '123' deleted",
"id":"123"
}
]
}
Errors:
401 - Forbidden
400 - Invalid parameter
Feature Attachments (Photos, Videos, Files) - Insert, Update and Delete photos and files for any feature using new GAE BlobStore.
Feature Feeds contain information on features within a datasource. The Edit feed contains all recent changes to individual features (create, update, delete) while the Full feed contains a paginated view of all features in the datasource. The Edit feed is particularly useful for syncronizing data on other servers or from client side applications.
Atom Feed
Json Feed
After a feature or features have been updated, you can optionally notify other servers of the changes instead of having them poll your Edit feeds. Polling clients can put a large strain on your server resources and while Google AppEngine will have no problem handling this strain, the wasted cost of replying to each polling request when no edits have occured should be avoided. There are two methods that built directly into your Cloud instance. A Manual WebHook is simply a remote server location that is POSTed to with the Json edit feed everytime it changes. A PubSubHubHub service is a third party service (free but public or pay for private) that handles all of the webhooks automatically and can scale to a very large number of server notifications.
Manual WebHooks (http://www.webhooks.org/)
PubSub (PubSubHubbub) - http://code.google.com/p/pubsubhubbub/