Regrid Typeahead API

This is documentation for the Regrid Typeahead API, a separate endpoint that couples nicely with our Parcel API. Please see the Using the API document for full reference on the Parcel API.

Requests

The endpoint is accessible via GET requests at:

https://app.regrid.com/api/v1/typeahead.json

Example request

GET https://app.regrid.com/api/v1/typeahead.json?token=TOKEN&query=407+e+f

Query parameters

  • token: Your Regrid assigned authorization token.
  • query: A street address or partial address, starting at the beginning

Response

You’ll receive a JSON array of matching results like the following. Note this is a lighter-weight format than our regular Parcel API and includes a few essential fields for display and/or further queries to the API.

Example response

[
  {
    "address":"407 E Fort St",
    "ll_uuid": "e94f20e8-afba-4ff9-bf14-3735bc706d0d",
    "score":0.95,
    "context":"Detroit, MI",
    "path":"/us/mi/wayne/detroit/181893",
    "centroid":[
      -83.0425191186133,
      42.3330336459147
    ]
  },
  {
    "address":"407 E Fort St Ste 100",
    "ll_uuid": "e94f20e8-afba-4ff9-bf14-3735bc706d0d",
    "score":0.95,
    "context":"Detroit, MI",
    "path":"/us/mi/wayne/detroit/181893",
    "centroid":[
      -83.0425191186133,
      42.3330336459147
    ]
  },
  {
    "address":"407 E Flint St",
    "ll_uuid": "01c4125d-be85-49d9-ab5f-990dc6f1fd7d",
    "score":0.95,
    "context":"Davison, MI",
    "path":"/us/mi/genesee/davison/186046",
    "centroid":[
      -83.512888738133,
      43.0352112045373
    ]
  },
]

Response fields

Notes

This is designed to accept natural input the way a user might type into a search box, including appending a city, state, or ZIP code to the query. We try our best to parse it intelligently and return meaningful results in real time. These would be acceptable queries

  • "407 e fort detroit"
  • "407 e fort detroit mi"
  • "407 e fort 48226"

Integrating the Typeahead API into your app

We suggest connecting your UI search widget directly to our API endpoints for the most responsive experience as users type an address.

Fetching complete parcel record details

We send a lightweight JSON response in the Typeahead API, including enough information to display results and allow a more complete lookup. To retrieve the full set of data fields for a parcel record, including geometry, please use our Parcel API to look up a record by ll_uuid, using a UUID chosen from the typeahead response.

Example client implementation (Javascript)

Here is a sample snippet using the typeahead.js library initially developed by Twitter. It supports search-as-you-type, displaying matches in a dropdown menu, and taking an action when a result is selected.

<html>
  <head>
    <title>Regrid Typeahead Demo<title>
    <!-- Load required libraries, your implementation will likely be different: -->
    <script src="https://code.jquery.com/jquery-2.2.4.min.js" integrity="sha256-BbhdlvQf/xTY9gja0Dq3HiwQF8LaCRTXxZKRutelT44=" crossorigin="anonymous"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/4.7.7/handlebars.min.js"
      integrity="sha512-RNLkV3d+aLtfcpEyFG8jRbnWHxUqVZozacROI4J2F1sTaDqo1dPQYs01OMi1t1w9Y2FdbSCDSQ2ZVdAC8bzgAg=="
      crossorigin="anonymous" referrerpolicy="no-referrer"></script>
    <script src="https://github.com/corejavascript/typeahead.js/raw/master/dist/typeahead.bundle.min.js"></script>
  </head>

  <body>
    <!-- Create an text input field to listen for typed search queries -->
    <input id='search' placeholder="Type an address here"/>

    <script>
      $(document).ready(function() {
        var token = 'YOUR_API_TOKEN';

        // Define the remote data source:
        var source = new Bloodhound({
          datumTokenizer: function (d) { return d; },
          queryTokenizer: function (d) { return d; },
          remote: {
            url: `https://app.regrid.com/api/v1/typeahead.json`,
            rateLimitBy: 'debounce',
            rateLimitWait: 100,
            prepare: function (query, settings) {
              var params = {
                query: query,
                token: token
              };
              settings.url = settings.url + '?' + $.param(params);
              return settings;
            }
          }
        });

        // Set up a typeahead UI on the text input field
        $('#search').typeahead(null, {
          name: 'address',
          display: 'address',
          source: source,
          limit: 20,
          templates: {
            suggestion: Handlebars.compile("<div> <span class='context'></span></div>")
          }
        }).on('typeahead:selected', function (e, o) {
          // When a result is clicked, we get its payload data in the 'o' argument as defined above,
          // which can be used for further action.

          if(o.centroid) {
            // If you have a map component, you may center the view there or create a marker:
            // The centroid pair is in [longitude, latitude] order.
            // map.setView([o.centroid[1], o.centroid[0]], 17);
          }
          // To go to the parcel on the Regrid platform, you may use the "path" of the parcel:
          var url = 'https://app.regrid.com' + o.path;

          // To fetch complete details, use the ll_uuid to form a request URL and create an XHR query:
          var url2 = `https://app.regrid.com/api/v1/parcel/${o.ll_uuid}.json?token=${token}`;

          e.preventDefault();
          e.stopPropagation();
          e.stopImmediatePropagation();
        });
      });
    </script>
  </body>
</html>