> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nodemaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Locations

> Look up the countries, regions, cities, ISPs and ZIP codes you can target, so your proxy usernames use values the network actually recognises.

The locations endpoints return the targeting values you put into a proxy username. Rather than hardcoding a country or city name and hoping it resolves, you query the list and use a value the network recognises.

All requests go to `https://api.nodemaven.com/api/v2/base/` and carry the header `Authorization: x-api-key YOUR_API_KEY`. See the [NodeMaven API overview](/proxy-api/overview) for the shared basics.

## Endpoints

| Method | Path | What it returns | Responses |
| - | - | - | - |
| `GET` | `/locations/all-doc/` | Documentation for ListCountries | 200 |
| `GET` | `/locations/countries/` | List of countries in a defined location | 200, 500 |
| `GET` | `/locations/regions/` | List of regions in a defined location | 200, 400, 500 |
| `GET` | `/locations/cities/` | List of cities in a defined location | 200, 400, 500 |
| `GET` | `/locations/isps/` | List of ISPs in a defined location | 200, 400, 500 |
| `GET` | `/locations/isps/regions/` | List of ISPs grouped by regions in a country | 200, 400, 500 |
| `GET` | `/locations/isps/cities/` | List of ISPs grouped by cities in a country | 200, 400, 500 |
| `GET` | `/locations/zipcodes/` | List of zip codes in a defined location | 200, 400, 500 |
| `GET` | `/locations/zipcodes/regions/` | List of zip codes grouped by regions in a country | 200, 400, 500 |
| `GET` | `/locations/zipcodes/cities/` | List of zip codes grouped by cities in a country | 200, 400, 500 |

```bash theme={null}
curl https://api.nodemaven.com/api/v2/base/locations/countries/ \
  -H "Authorization: x-api-key YOUR_API_KEY"
```

## Query parameters

Every locations endpoint is paginated and **requires `limit` and `offset`**. These four parameters are shared across all of them:

| Parameter | Type | Notes |
| - | - | - |
| `limit` | integer | Results per page. Defaults to `50`. Maximum `1000` |
| `offset` | integer | Index to start from |
| `connection_type` | string | `residential` or `mobile`. Defaults to `residential` if omitted |
| `ipv4_only` | boolean | When true, only returns locations from IPv4-capable providers |

On top of those, each level takes its own filters.

`GET /locations/countries/` also takes:

| Parameter | Type | Notes |
| - | - | - |
| `name` | string | Maximum 50 characters |
| `code` | string | Maximum 50 characters |

`GET /locations/regions/` **requires `country__code`**, because regions are always looked up inside a country:

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `country__code` | string | Yes | Maximum 50 characters |
| `name` | string | No | Maximum 100 characters |
| `code` | string | No | Maximum 100 characters |

<Warning>
  **`country__code` has a double underscore.** Written with a single underscore the parameter is not recognised, so the required country code counts as missing.
</Warning>

The cities, ISP and ZIP code endpoints follow the same drill-down pattern: pass the pagination parameters, then the code of the level above the one you are listing.

Three things to carry across every call: pagination is required, a country code is required once you go below country level, and the connection type is residential unless you say otherwise.

## Targeting limits to know about

Two constraints will change which of these endpoints are useful to you:

* **ZIP code targeting is United States only.** See [ISP and ZIP targeting](/residential-mobile/isp-and-zip-targeting).
* **ISP proxies are targeted at country level only.** City, region and ISP-level targeting applies to Residential and Mobile, not to ISP proxies. See [ISP proxy locations](/isp/locations).

## Related reading

* [Locations](/residential-mobile/locations) covers location targeting for Residential and Mobile in the dashboard.
* [Proxy string](/residential-mobile/proxy-string) shows where these values go in the username.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.