Package: amigocloud
Python client for theAmigoCloudREST
API.InstallationInstall via pip:pip install amigocloudDependenciesrequests: Handles the HTTP requests to the AmigoCloud REST API.gevent: Handles the websocket connections.socketIO_client: Handles the AmigoCloud websocket connection.six: A library to assit with python2 to python3 compatibility.This dependencies will be automatically installed.UsageAuthenticationThis library uses API token to authenticate you. To generate or access your API tokens, go toAPI tokens.fromamigocloudimportAmigoCloudamigocloud=AmigoCloud(token='R:dlNDEiOWciP3y26kG2cHklYpr2HIPK40HD32r1')You could also use a project token. Remember that project tokens can only be used to query endpoints relative to the project it belongs to.
If the project URL doesn’t match its project,AmigoCloudErrorwill be thrown.fromamigocloudimportAmigoCloudamigocloud=AmigoCloud(token='C:Ndl3xGWeasYt9rqyuVsByf5HPMAGyte10y1Mub',project_url='users/123/projects/1234')You can use a READ token if you only want to do requests that won’t alter data. Otherwise, you’ll need to use more permissive tokens.RequestsOnce you’re logged in you can start making requests to the server. You
can use full urls or relative API urls:# All three will do the same request:amigocloud.get('me')amigocloud.get('/me')amigocloud.get('https://www.amigocloud.com/api/v1/me')For convenience, when using project tokens, urls are relative to the project’s url (unless it starts with/):# All three will do the same request:amigocloud.get('datasets')amigocloud.get('/users/123/projects/1234/datasets')amigocloud.get('https://www.amigocloud.com/api/v1/users/123/projects/1234/datasets')Creating a new AmigoCloud project from Python is as simple as:data={'name':'New Project','description':'Created from Python'}amigocloud.post('me/projects',data)All responses are parsed as JSON and return a Python object (usually adict). This data can be later used in another request:me=amigocloud.get('me')visible_projects=amigocloud.get(me['visible_projects'])print'My projects:'forprojectinvisible_projects['results']:print'*',project['name']You can get the raw response if you want by using therawparameter:me=amigocloud.get('me')images=amigocloud.get(me['images'])withopen('thumbnail.png','wb')asthumbnail:image_data=amigocloud.get(images['thumbnail'],raw=True)thumbnail.write(image_data)Cursor RequestsMany requests return a paginated list. For example: projects, datasets, base layers,
and sql queries. They can be identified when the request returns a dictionary with
four items.fromamigocloudimportAmigoCloudamigocloud=AmigoCloud(token='yourapitoken')project_list=amigocloud.get('/me/projects')pprint(project_list)will return a dictionary like this (modified for brevity):{u'count':319,u'next':u'https://app.amigocloud.com/api/v1/me/projects?limit=20&offset=20&token=yourapitoken',u'previous':None,u'results':[]}From the results, you can see that this endpoint can be iterated through.
To make it easier to iterate through these lists, you can use theget_cursorfunction. The cursor iterates over the results and if it reaches the limit of
the response it will automatically make a request to get the next values. So
you can get all data and iterate over it, without worrying about the
pagination.projects=amigocloud.get_cursor('/me/projects')forprojectinprojects:print('Project:',project['name'])If you want to iterate one request at a time it can be requested as:# using a project token to authenticatedatasets=amigocloud.get_cursor('datasets')dataset1=datasets.next()print('Dataset1:',dataset1['name'])# Boolean to ask if there is a next value.# otherwise a StopIteration exception is raised.ifdatasets.has_next:dataset2=datasets.next()print('Dataset2:',dataset2['name'])Also, you can request some extra values, that are included in the response.dataset_rows=amigocloud.get_cursor('https://www.amigocloud.com/api/v1/projects/1234/sql',{'query':'select * from dataset_1'})print('Response extra values:',dataset_rows.get('columns'))forrowindataset_rows:print('Row:',row)Cursors can be used for Projects, Datasets, BaseLayers, SQL queries, etc.
It also supports non-iterable responses. For this cases it returns only one result.cursor=amigocloud.get_cursor('me')formeincursor:print('Me:',me)Websocket connectionThe websocket connection is started when the AmigoCloud object is
instantiated, and it is closed when the object is destroyed. You always
need to use a user token for websockets.Make sure to readour help page about our websocket eventsbefore continue reading.To start listening to websocket events related to your user (multicast
events), do (you must be logged in to start listening to your events):amigocloud.listen_user_events()Once you’re listening to your events, you can start adding callbacks to
them. A callback is a function that will be called everytime the event
is received. These functions should have only one parameter, that would be a python dict.defproject_created(data):print'User id=%(user_id)screated project id=%(project_id)s'%dataamigocloud.add_callback('project:creation_succeeded',project_created)Realtime events are broadcast events related to realtime dataset. To start listening to them, do:amigocloud.listen_dataset_events(owner_id,project_id,dataset_id)Then add a callback for them:defrealtime(data):print'Realtime dataset id=%(dataset_id)s'%dataforobjindata['data']:print"Object '%(object_id)s' is now at (%(latitude)s,%(longitude)s)"%objamigocloud.add_callback('realtime',realtime)Finally, start running the websocket client:ac.start_listening()This method receives an optional parameterseconds. IfsecondsisNone(default value), the client will listen forever. You might
want to run this method in a new thread.ExceptionsAnAmigoCloudErrorexception will be raised if anything fails during
the request:try:amigocloud.post('me/projects')exceptAmigoCloudErroraserr:print'Something failed!'print'Status code was',err.response.status_codeprint'Message from server was',err.text