Nearby Nonprofit Search
Use the /nearby endpoint to find nonprofits within a radius of a ZIP code or latitude/longitude pair. Nearby search returns distance in miles and supports filtering, sorting, pagination, and field selection.
Endpoint
Use nearby search when location and distance are central to the request.
Basic nearby request
Find nonprofits within 25 miles of ZIP code 28403.
GET /nearby?origin_zip=28403&radius=25&fields=ein,name,city,state,ntee_group,distance_miles&limit=5Nearby results are sorted by distance_miles ascending by default, with nonprofit name used as a secondary sort for stable ordering.
Search origin
Every nearby request needs either coordinates or an origin ZIP code.
Provide either lat and lng together, or provide origin_zip. If both are provided, lat and lng are used as the search origin.
GET /nearby?origin_zip=28403&radius=25GET /nearby?lat=34.2257&lng=-77.9447&radius=25| key | type | required | multi | example | description |
|---|---|---|---|---|---|
| lat | number | Conditional | No | 34.2257 | Latitude for the search origin. Must be used with lng. |
| lng | number | Conditional | No | -77.9447 | Longitude for the search origin. Must be used with lat. |
| origin_zip | string | Conditional | No | 28403 | ZIP code used as the search origin. Ignored if lat and lng are provided. |
| radius | number | No | No | 10 | Search radius in miles. Defaults to 10. Maximum depends on your API tier. |
Distance results
Nearby search can return calculated distance from the search origin.
The distance_miles field is only available on /nearby. It is calculated from the search origin and can be requested with the fields parameter.
GET /nearby?origin_zip=28403&radius=25&fields=ein,name,city,state,distance_miles&limit=5| key | type | description |
|---|---|---|
| distance_miles | number | Distance from the search origin in miles. Only returned by /nearby. |
Filtering nearby results
Narrow nearby nonprofits by cause, IRS classification, financial ranges, and other fields.
Filters are passed as query parameters. Some filters accept comma-separated or repeated values depending on your query parser and schema configuration.
GET /nearby?origin_zip=28403&radius=25&ntee_code=D20,W30&limit=25Filters that support multiple values are marked as multi in the tables below.
Metadata-validated filters
These filters are validated against CharityQuery metadata definitions.
- Values are checked against the same code definitions exposed by the metadata endpoints.
- Many IRS codes contain leading zeros. Treat code values as strings.
- Invalid values return a
400validation error.
| key | type | multi | validation | metadataRoute | example | description |
|---|---|---|---|---|---|---|
| ntee_code | string | Yes | metadata | /metadata/ntee-codes | 'B80' | Filters by exact NTEE code. IRS provided values are all 3 strings. 1 letter and 2 numbers |
| ntee_group | string | Yes | metadata | /metadata/ntee-groups | 'B' | Filters by NTEE general group. |
| account_paid | string | Yes | metadata | /metadata/account-paid-code | '01' | Filters by IRS account paid codes as a proxy for month number starting at 01 (January) and ending at 12 (December). |
| pf_filing_req_code | string | No | metadata | /metadata/pf-required-codes | '0' | Filters by IRS PF Filing Required codes. |
| filing_req_code | string | Yes | metadata | /metadata/filing-required-codes | '07' | Filters by IRS Filing Required codes. |
| organization | string | Yes | metadata | /metadata/organization-codes | '2' | Filters by IRS Organization codes. |
| status | string | Yes | metadata | /metadata/status-codes | '02' | Filters by IRS Status codes. |
| affiliation | string | Yes | metadata | /metadata/affiliation-codes | '6' | Filters by IRS Affiliation codes. |
| deductibility | string | Yes | metadata | /metadata/deductibility-codes | '1' | Filters by IRS deductibility codes. |
| foundation | string | Yes | metadata | /metadata/foundation-codes | '1' | Filters by IRS foundation codes. |
| geocode_status | number | Yes | metadata | /metadata/geocode-status | 22 | Filters by how the charity recieved its coordinates |
Subsection and classification
These two filters must be provided together.
subsectionandclassificationmust be used together on/nearby.- The paired combination provides a more precise IRS classification than either value alone.
- Use
/metadata/subsection-classificationto get valid paired combinations when building UI filters.
GET /nearby?origin_zip=28403&subsection=03&classification=2000| key | type | multi | validation | metadataRoute | example | description |
|---|---|---|---|---|---|---|
| subsection | string | No | metadata | /metadata/subsection-classification-codes | '03' | Filters by IRS subsection code. Must be used with classification. |
| classification | string | No | metadata | /metadata/subsection-classification-codes | '1000' | Filters by IRS classification code. Must be used with subsection. |
Direct match filters
These filters match against stored nonprofit data.
- Values are treated as strings. Fields such as
groupmay contain leading zeros. - Direct match filters are best for known values such as state, IRS group, ruling date, activity, or tax period.
- Nearby search uses
origin_zip,lat,lng, andradiusfor the search origin.
| key | type | multi | validation | example | description |
|---|---|---|---|---|---|
| name | string | No | direct | Marine Corps League | Filters by charity name. |
| ico | string | No | direct | Bob Ross | Filters by ICO (In Care Of). |
| state | string | Yes | direct | NC or nc | Filters by state abbreviation. |
| group | string | No | direct | 0955 | Filters by group exemption number. |
| ruling | string | No | direct | 199601 | Filters by ruling date code (YYYYMM). |
| tax_period | string | No | direct | 202506 | Filters by Tax Period, which is the last date they filed (YYYYMM) |
| activity | string | No | direct | 000111222 | Filters by activity code. This code was depricated in favor of the NTEE Code, but still exists on some charities. |
Financial range filters
Search nearby nonprofits by asset, income, and revenue amounts.
Range filters let you set minimum and maximum values. You can use one side of a range or combine both.
GET /nearby?origin_zip=28403&radius=25&income_amount_gte=1000&income_amount_lte=10000&limit=25| key | type | multi | validation | description | example |
|---|---|---|---|---|---|
| asset_amount_gte | number | No | numeric | Minimum asset amount. | 100000 |
| asset_amount_lte | number | No | numeric | Maximum asset amount. | 500000 |
| income_amount_gte | number | No | numeric | Minimum income amount. | 1000 |
| income_amount_lte | number | No | numeric | Maximum income amount. | 10000 |
| revenue_amount_gte | number | No | numeric | Minimum revenue amount. | 1000 |
| revenue_amount_lte | number | No | numeric | Maximum revenue amount. | 10000 |
Pagination
Control how many nearby results are returned and move through result pages.
GET /nearby?origin_zip=28403&radius=25&limit=25&page=2| key | type | multi | example | default | description |
|---|---|---|---|---|---|
| limit | number | No | 75 | 25 | Sets the max number of returned items. Defaults to 25. Maximum depends on the endpoint and your API tier. |
| page | number | No | 26 | 1 | Sets the page. |
Sorting
Control the order of nearby results.
By default, /nearby sorts by distance_miles ascending. You can also sort by supported public fields. Sorting does not require the field to be included in fields.
GET /nearby?origin_zip=28403&radius=25&sortBy=distance_miles&sortDir=asc&limit=25| key | type | multi | validation | example | description |
|---|---|---|---|---|---|
| sortBy | string | No | enum | distance_miles | Sorts nearby results by a supported field. Defaults to distance_miles. |
| sortDir | string | No | enum | asc | Sort direction. Use asc or desc. |
Example: find animal-related nonprofits nearby
Combine radius search, metadata filters, field selection, and sorting.
GET /nearby?origin_zip=28403&radius=50&ntee_group=D&fields=ein,name,city,state,ntee_group,distance_miles&sortBy=distance_miles&sortDir=asc&limit=10This request finds nearby animal-related nonprofits, returns a compact response, and orders results by distance.