New Zip Code Radius search in GuideStar Search V1_1 API

Document created by JackCowardin Administrator on Jul 28, 2017Last modified by JackCowardin Administrator on Jul 28, 2017
Version 2Show Document
  • View in full screen mode

Responding to customer requests, GuideStar has added a Zip Code Radius search capability to the Search V1_1 REST API. The Radius Search adds two new parameters for use with the Search API:

 

These are:

  • zipcode - the five digit US Postal Service zip code. Zip Plus 4 is not supported.
  • radius - the radius of a circle surrounding the given zip code in miles.

 

The zipcode parameter is not the same as the zip data field returned by the Search API. The zip keyword (data field) is part of the Lucene index and is a data element that is returned by the API. Note that the zip code radius search query requires an initial parameter to establish a set of results.  In the second example below, the search term “education” establishes the set of results. The zipcode and radius parameters then filter that set to include only the organizations that meet the zip code and radius criteria.

 

For example, this standard zip code search query, using the "zip" keyword will return all organizations that have the “20001” value in the zip field:

https://data.guidestar.org/v1_1/search.json?q=zip:20001

This search returns (results are abbreviated to show only the number of "hits"): 

// https://data.guidestar.org/v1_1/search.json?q=zip:20001

{"total_hits": 1775,

 

The zipcode parameter is a new parameter that invokes the radius search function and must be accompanied by the radius parameter, as well as an initial keyword parameter (e.g., “education”). The example below uses the same zipcode with a radius of 10 miles:

https://data.guidestar.org/v1_1/search.json?q=education&zipcode:20001&radius=10

 This search returns:

//https://data.guidestar.org /v1_1/search.json?q=education&zipcode=20001&radius=10

{"total_hits": 6008

 

Increasing the radius to 15 miles we get:

https://data.guidestar.org/v1_1/search.json?q=education&zipcode:20001&radius=15

 

//https://data.guidestar.org/v1_1/search.json?q=education&zipcode=20001&radius=15

{"total_hits": 7073

 

If the Search you want to is for all organizations within a certain zipcode radius, and not a subgroup defined by a keyword such as “education”, then the initial keyword parameter should be one that establishes the set of all organizations. In Lucene syntax, this would be given as q=*:*. The asterisk “*” is a wildcard character, and, in this syntax, each asterisk is separated by a colon (not a period), and says “give me all organizations that have any value in any field".

 

Once that set is selected, we apply the zipcode and radius parameters to filter the results, as follows:

https://data.guidestar.org/v1_1/search.json?q=*:*&zipcode:20001&radius=15

 

http://data.guidestar.org/v1_1/search.json?q=*:*&zipcode=20001&radius=15

{  "total_hits": 50760

 

As always, if you have any difficulty using the new Zip Code Radius feature of Search version 1_1, please contact apisupport@guidestar.org by email and we will assist you in formulating the correct search.

Attachments

    Outcomes