Using the Typeahead API

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

Requests

The endpoint is accessible via GET requests at:

https://app.regrid.com/api/v2/typeahead

Example request

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

Query parameters

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

Response

You'll receive an object containing a GeoJSON Feature Collection containing a list of Features of matching results like the following. Note this is a lighter-weight response than our regular Parcel API and includes a few essential fields for display and/or further queries to the API.

Response fields

  • parcel_centroids: A GeoJSON Features Collection of Features, sorted by descending relevance rank, containing a subset of parcel fields and a Point geometry for the centroid of each Parcel Record.

    • geometry: A GeoJSON Point geometry of the parcel centroid. Note that this is in 'lon, lat' order.
    • properties

Example response

{
    "parcel_centroids": {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "properties": {
                    "address": "407 E Fort St",
                    "ll_uuid": "e94f20e8-afba-4ff9-bf14-3735bc706d0d",
                    "score": 95,
                    "context": "Detroit, MI",
                    "path": "/us/mi/wayne/detroit/181893"
                },
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -83.0425191186133,
                        42.3330336459147
                    ]
                }
            },
            {
                "type": "Feature",
                "properties": {
                    "address": "407 E Fort St Ste 100",
                    "ll_uuid": "e94f20e8-afba-4ff9-bf14-3735bc706d0d",
                    "score": 95,
                    "context": "Detroit, MI",
                    "path": "/us/mi/wayne/detroit/181893",
                    "geometry": {
                        "type": "Point",
                        "coordinates": [
                            -83.0425191186133,
                            42.3330336459147
                        ]
                    }
                }
            },
            {
                "type": "Feature",
                "properties": {
                    "address": "407 E Flint St",
                    "ll_uuid": "01c4125d-be85-49d9-ab5f-990dc6f1fd7d",
                    "score": 95,
                    "context": "Davison, MI",
                    "path": "/us/mi/genesee/davison/186046"
                },
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -83.0425191186133,
                        42.3330336459147
                    ]
                }
            }
        ]
    }
}

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/v2/typeahead`,
            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.features,
          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 GeoJSON Feature in the 'o' argument as defined above,
          // which can be used for further action.

          if(o.geometry) {
            // 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.geometry.coordinates[1], o.geometry.coordinates[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.properties.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/v2/parcel/${o.properties.ll_uuid}?token=${token}`;

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

Notes for client implementation

There are two types of addresses that get loaded, one with address without city, state and zip and a complete address with city, state and zip. We use two sources for the address and provide all options. They are sorted by most relevant to what is entered in the query. The ll_uuid for the address is still the same but this gives the user the flexibility to choose which format to ingest. This also helps when a parcel address has multiple units or secondary addresses.

If you are implementing Typeahead API and interested in one result, you can add a client-side filter in Javascript to keep only the first entry for each ll_uuid.

In this section