ArcREST Basics - ArcGIS Online and Query()

In this weeks ArcREST basics series, I am going to go into the how to connect to your organization on ArcGIS Online (AGOL) using Python, and perform some basic queries using the manageorg sub-package in ArcREST.

First we start by building off the previous lesson and create a security handler object for AGOL.  If you missed a deeper discussion on how to handle security, please see this post.

One of the most common tasks to perform when working with your site, is to query it to see what content you have.  There are two ways to query a site:

1. With Credentials - this means a token will be appended on the end of the query search, and users can find both public and non-public items if your users has the proper permissions to do so.
2. Without Credentials - this means only find public items shared with everyone.

In the example below, a query is being performed with credentials being given.  This means case #1 will be applied.

from arcrest.security import AGOLTokenSecurityHandler
from arcrest.manageorg import Administration
if __name__ == "__main__":
    username = "username"
    password = "password"
    proxy_port = None
    proxy_url = None    
    securityHandler = AGOLTokenSecurityHandler(username, password,
                                               proxy_url=proxy_url,
                                               proxy_port=proxy_port)
    siteObject = Administration(securityHandler=securityHandler,
                                proxy_url=proxy_url,
                                proxy_port=proxy_port)
    results = siteObject.query(q="< some query string >")

This returns a Python dictionary object as shown below:

{
   "query" : "type:feature class",
   "total" : 12345,
   "start" : 1,
   "num" : 10,
   "nextStart" : 11,
   "results" : [ ...list of items... ]
}

Let us examine the results object.  It's a dictionary with many valuable key/value pairs.  Since this query was performed using the default values, this means that the query will begin with the first item and go to the 10th item (num).  The key nextStart tells you where the start value needs to be if you want to page each result.  So the next time you pass the query in order to get all the results you need to set the start = 11.  Manually this seems quite daunting task, but luckily for us, we have looks.  There are many way to create loops to perform this task, but in this example, a while loop will be used to walk the results and put them in a single list object.

def findContentByDate(admin, q):
    """
       finds items based on a query (q)

       Inputs:
    
          admin - manageorg.Administration object
          q - query string
    """
    start = 1
    count  = 0
    nextStart = 0
    num = 100
    results = []
    while nextStart != -1:
        query = admin.query(q=q,
                        sortOrder="desc",
                        sortField="modified",
                        t=None,
                        start=start + (count * num),
                        num=100)
        results = results + query['results']
        nextStart = query['nextStart']
        count += 1
    return results

Now we have all the items based on a query in a single Python list. This is very helpful in cataloging a site/org or even good for finding publicly shared items.

AGOL has it's own query language much like the google or other search engines.  This documentation can be found here (http://doc.arcgis.com/en/arcgis-online/reference/search.htm).  It is a must read for anyone who wants to query AGOL or Portal effectively.

Though the samples shown are created to work with Portal, then same example can be used to query a Portal site.

If you want to learn more, please visit the ArcREST Github Page.  Help us make it better and post comments, suggestions and improvements in the Issues section.  Or better yet, fork the repo and submit a pull request.

Happy Coding and Enjoy!