Getting Started with API

The Regrid API offers a flexible and dynamic set of features for querying Regrid Parcels by numerous fields, operators, geometries and allows for simple composition of API calls, from the output of one endpoint, to the input of another.

Our OpenAPI specification is available for download in the API section of your account, and in usable form in our API Sandbox. The following documentation expands upon the endpoint descriptions and field name and operator use in the OpenAPI spec.

Endpoints

All API requests are to the https://app.regrid.com/ domain. You can review our full description of endpoints at Regrid API Endpoints.

Responses

All API requests return a GeoJSON Feature Collection object containing an array of GeoJSON Features. Each Feature contains one Parcel Record with all of its attributes in the properties object and its GeoJSON geometry in the geometry object. A Feature Collection with an empty features array means no Parcel Records could be matched based on the search criteria.

API Billing

Parcel API requests are billed by the number of parcel records returned in each response. The number of API calls you make doesn't determine your bill. The number of parcel records those calls return does.

One request can return many records, depending on how you search. Searches by address, parcel number, owner name, polygon, and point (with or without a radius) can all return multiple parcel records in a single response.

A few rules follow from this:

• Returned means billed. Every record in the response counts, even if your application filters it out, hides it, or never shows it to a user.
• Empty responses cost nothing. A request that matches no parcels returns zero records and adds nothing to your usage.
• Record size doesn't change the count. One parcel record counts as one record, whether or not you ask for geometry or extra fields.

Every request is billed on its own

The API treats each request independently. It doesn't remember which parcels, coordinates, or search areas your account has asked for before. If your application sends the same request twice, the API does the full work twice and returns the full response twice, and both responses count toward your usage.

This applies to:

• Repeated lookups. Querying the same coordinate, address, or APN again, whether minutes or weeks later.
• Re-runs of batch jobs. A job that restarts from the beginning, or two copies of a job running at once, bills for every record again.
• Pagination. When a search matches more records than the limit, the offset_id parameter returns the next set of results. Each page is a separate request, and every record on it is billed.

Controlling how many records a request returns

The limit parameter caps the number of parcel records a request can return. The default is 20, and it can be set anywhere from 1 to 1,000. It's the most important cost control available in each request.

Guidelines:

• Set the limit to what you need. If you only need the one parcel at a location, use limit=1. If you only show 25 results, request 25.
• Use radius carefully. On point searches, radius sets a search area in meters, and every parcel within that area is returned, up to the limit. A small radius can help when a point lands just outside a parcel boundary, such as in the street. A large radius with a high limit can return many neighboring parcels you didn't need.
• Keep polygon searches small. A polygon covering part of a city can contain tens of thousands of parcels. Require users to narrow the area before searching.
• Don't page through results automatically. Fetch the next page only when a user asks for more.
• Use targeted lookups when possible. When you already know the property, lookups by point, address, or APN with a low limit return far fewer records than area searches.

Examples

Caching responses on your side

Because every request is billed, the most effective way to avoid paying twice for the same data is client-side caching. This means your application stores the responses it receives, for example in a database, and checks that store before calling the API. If the answer is already stored, your application uses it and no request is sent, so nothing is billed.

Our platform doesn't cache or de-duplicate requests for you, and it doesn't discount repeat requests. Caching lives in your systems and is controlled by your code.

Parcel data can be cached for up to 30 days. This is permission to store and reuse responses within that window. It isn't a promise that repeat requests within the window will be free.

A basic caching setup:

1. Before a lookup, check your cache for that coordinate, APN, or address.
2. If a fresh stored result exists, use it.
3. If not, call the API and save the response with a timestamp.
4. Refresh stored results only after your caching window has passed.
   For batch jobs, also make sure only one copy of the job can run at a time. Have it skip or resume from records already processed rather than starting over.

Plan allowances and overages

Self-serve monthly plans use a hybrid usage model. Each monthly plan includes 2,000 parcel records and 200,000 tiles. Usage beyond those amounts in a month is billed as overage:

Your included records apply to all Parcel API usage in the billing cycle. Records from testing, repeated requests, and pagination all count toward the allowance and any overage.

Monitoring usage and preventing surprises

• Usage endpoint. The Account Usage endpoint (GET /api/v2/usage) shows real-time usage, including parcel records used in your plan. It's free to call. Check it before running large jobs.
• Detailed usage. The detailed usage endpoint (GET /usage/detailed) breaks down your usage by endpoint, date, and query type. Use it to see which requests are driving usage.
• Spending caps. In your account dashboard, you can set a monthly maximum price for API usage.
• Usage alerts. You can also set email alerts that notify you as you approach your usage limit.
• Test with small limits. When building or testing an integration, use limit=1 or a small number, and try a handful of requests before running a full batch.

Authentication

All API requests must include a token parameter. You can find and generate new tokens in the API section of your regrid.com Account Profile.

Learn more about API Token Management.

API request rates

API request rates are defined in terms of the maximum number of requests allowed per minute. Exceeding the API request rate will result in a 429 error for rate limiting/throttling. The API server will reject any additional requests until the rate limit resets. It is important to adhere to the rate limits to avoid disruption in service and ensure compliance with the Regrid Terms of Use.

Rates are limited to 10 simultaneous API requests or approximately 200 API requests per minute. Additional capacity is available; please contact our sales team at [email protected] for details.