---
title: "List stations close to you or filter by search criteria"
method: GET
path: "/v3/stations"
tags: ["stationfinder"]
---

# List stations close to you or filter by search criteria

`GET /v3/stations`

This endpoint has two main use cases:

- If no query parameters passed in, it returns a list of stations that are geographically closest to the calling client (based on GeoIP information)
- If one or more query parameters are passed in, it performs a search of NPR stations that match those search criteria (not taking into account the client's physical location)

Clients wanting to implement a 'Change Station' UI should use this endpoint to power their search. In most cases, you'll want to build a search interface that uses one of the 3 provided schemas: `lat` and `lon` (using e.g. the HTML5 Geolocation API), `city` and `state`, _or_ the generic `q` query which can accept a station name, call letters, network name, or zip code. Technically speaking, `q` can also take in either a city name or a state name, but using the `city` and `state` parameters together will yield more accurate geographic search results than `q={cityName}`.

The `lat` and `lon` query parameters should always be passed in together (otherwise the API will return a 400 error), and if included in the query, they will take precedence over any other search criteria; that is, `lat` and `lon` will do a purely geographic search and not take into account `q`, `city` or `state`.

Similarly, `city` and/or `state` will take precedence over (and ignore) `q`.

If clients want to be able to offer multiple types of searches (e.g. 'Search for a station name, city or zipcode') using a *single* search input form, `q` should be used. But again, be aware that using `city` and `state` together will yield more accurate search results than `q={cityName}`.

## Query parameters

- `q` string
- `city` string
- `state` string
- `lat` number, float
- `lon` number, float

## Headers

- `Authorization` string, required

## Response `200`

A list of one or more stations matching the search query

- StationListDocument — A collection of stations close to you or filtered by search criteria
  - `attributes` object, required
    - `city` string — The city searched for in the original request
    - `countryCode` string — The country where the original request originated, as determined by geolocation. The countryCode is in ISO 3166-1 numeric format
    - `lat` number, float — The latitude parameter used in the original request
    - `lon` number, float — The longitude parameter in the original request
    - `query` string — The search terms used in the original request
    - `state` string — The state searched for in the original request
  - `errors` object[], required — A list of encountered errors, ignored on POST, PUT
  - `href` string, required — A URL representation of the resource; should generally be ignored by clients unless noted otherwise
  - `items` object[], required — A list of stations
    - `attributes` object, required
      - `brand` StationBrandData, required — An associative array of brand-related metadata for this station
        - `band` 'FM' | 'AM' — The subsection of the radio spectrum -- 'AM' or 'FM' -- where this station can be heard
        - `call` string — The three-to-four-letter identifying code for this station. Please use this with caution; most stations prefer to be identified by their `name` in client applications instead of `call`.
        - `frequency` string — Where on the radio dial the station can be heard. If the `band` is AM, the frequency will be between 540 and 1600. If the `band` is FM, the frequency will be between 87.8 and 108.0.
        - `marketCity` string, required — The city that the station is most closely associated with. This may or may not be the city the station is licensed in and it may or may not be the city that the station or the station's antenna is located in.
        - `marketState` string, required — The state that the station is most closely associated with. This may or may not be the state the station is licensed in and it may or may not be the state that the station or the station's antenna is located in.
        - `name` string, required — The display name for the station. In most cases, this will be the same as `call` letters combined with band. When returning networks, it will return the network name (e.g. Minnesota Public Radio).
        - `tagline` string, required — A short text-logo for the station
      - `eligibility` StationEligibilityData, required — An associative array of eligibility-related metadata for this station
        - `format` string, required — The format of the programming on this station
        - `localization` string — Whether or not this station should be shown in search for news context, any context or no context
        - `musicOnly` boolean, required — Whether or not this station only plays music. Deprecated.
        - `nprOne` boolean, required — Whether or not this station is considered an NPR One station
        - `status` '1' | '9' | '10' | '12' | '15', required — The status of the station within NPR's system, not typically used by consumers
      - `guid` string, required — The system's internal unique identifier for a station, not typically used by other APIs or consumers
      - `network` StationNetworkData, required — Metadata about the network, if this station is part of a network
        - `currentOrgId` string, required — The current station being viewed. Client applications should generally ignore this field.
        - `tier1` StationNetworkTierOneData — Metadata about the top-level organization in the network, if this station is part of a network
          - `id` string, required — The unique identifier of the top-level organization in the network
          - `name` string, required — The display name for the top-level organization in the network
          - `status` '1' | '9' | '10' | '12' | '15' — The status of the top-level organization within NPR's system, not typically used by consumers
          - `tier2` StationNetworkTierTwoData[] — One or more stations that are hierarchical children of this organization
            - `id` string, required — The unique identifier of a tier 2 organization in the network
            - `name` string, required — The display name for a tier 2 organization in the network
            - `tier3` StationNetworkTierThreeData[] — One or more stations that are hierarchical children of this organization
              - …
            - `usesInheritance` boolean, required — Whether or not this station inherits from a parent organization, also referred to as a network
          - `usesInheritance` boolean, required — Whether or not this station inherits from a parent organization, also referred to as a network
        - `usesInheritance` boolean, required — Whether or not the current station inherits from a parent organization, also referred to as a network
      - `newscast` StationNewscastData — Metadata about the newscast for this station; newscasts are handled internally by other microservices such as the NPR One Listening Service, so this data should typically not be used by consumers
        - `id` string, required — The ID of the newscast that should be played for this station; this is handled internally by other microservices such as the NPR One Listening Service, so this field should typically not be used by consumers
        - `recency` integer, required — How often the newscast should be played, in minutes; a value of `null` implies no information is available, and sensible defaults should be used
      - `orgId` string, required — The system's unique ID for this station, used across NPR One Microservices and NPR's other APIs
    - `errors` object[], required — A list of encountered errors, ignored on POST, PUT
    - `href` string, required — A URL representation of the resource; should generally be ignored by clients unless noted otherwise
    - `items` object[], required — Not used
    - `links` object, required
      - `brand` StationBrandLink[], required — One or more links to a web page for the station
        - `href` string, uri, required — The link to be followed
        - `content-type` string, required — The MIME type of the response of this link
        - `rel` 'homepage' | 'logo' | 'small-logo' | 'hello-id-audio' | 'station-message-audio' | 'twitter' | 'facebook', required — A short string identifier describing the way the way the link relates to the document
      - `donation` StationDonationLink[] — One or more links to audio files related to this station
        - `href` string, uri, required — The link to be followed
        - `guid` string — The system's internal unique identifier for a link, not typically used by consumers
        - `title` string — The link text, provided by the station, for the URL
        - `typeName` string, required — The semantic name corresponding to the `typeId`
        - `typeId` '4' | '27' | '28' | '29', required — An identifier for the type of link; '4' denotes a generic pledge page, while '27' is an NPR One-specific pledge page
      - `podcasts` StationPodcastsLink[] — One or more links to podcasts related to this station
        - `href` string, uri, required — The link to be followed
        - `guid` string — The system's internal unique identifier for a link, not typically used by consumers
        - `title` string — The link text, provided by the station, for the URL
        - `typeName` string, required — The semantic name corresponding to the `typeId`
        - `typeId` '9', required — An identifier for the type of link
      - `related` StationRelatedLink[] — One or more links to miscellaneous related content for the station; these typically are not present, and clients should generally not need to use any of these
        - `href` string, uri, required — The link to be followed
        - `guid` string — The system's internal unique identifier for a link, not typically used by consumers
        - `title` string — The link text, provided by the station, for the URL
        - `typeName` string, required — The semantic name corresponding to the `typeId`
        - `typeId` string, required — An identifier for the type of link
      - `streams` StationStreamsLink[] — One or more links to audio streams related to the station
        - `href` string, uri, required — The link to be followed
        - `guid` string — The system's internal unique identifier for a link, not typically used by consumers
        - `title` string — The link text, provided by the station, for the URL
        - `typeName` string, required — The semantic name corresponding to the `typeId`
        - `isPrimaryStream` boolean — Whether or not this stream is considered the station's primary stream
        - `typeId` '10' | '11' | '12' | '13', required — An identifier for the type of stream
    - `version` string, required — The version of the Collection.Doc+JSON spec being used
  - `links` object, required — Not used
  - `version` string, required — The version of the Collection.Doc+JSON spec being used

## Other responses

- `400` — A bad request; generally, one or more parameters passed in were incorrect or missing
- `401` — The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers.
- `429` — The client has exceeded the number of daily calls as per their rate limit. For now, this only applies to prototype applications and untrusted clients. Trusted clients will never be rate-limited, nor will any production apps.
- `500` — A server error
- `503` — The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.

---

[API](https://skmtc.net/npr/apis/station-finder.md) · [All operations](https://skmtc.net/npr/apis/station-finder/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/npr/station-finder/revisions/ba8433fdbbc7/schema)