> For the complete documentation index, see [llms.txt](https://docs.gridstatus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gridstatus.io/developers/api-reference/pricing-locations.md). # Pricing Locations ## List Pricing Locations > Get a list of pricing locations with optional filtering by ISOs, zones,\ > zone types and a search term.\ > \ > Args:\ > params: Query parameters for filtering pricing locations\ > sort\_column: Column to sort by.\ > sort\_order: Sort order - 'asc' or 'desc'. ```json {"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/pricing_locations":{"get":{"tags":["Pricing Locations"],"summary":"List Pricing Locations","description":"Get a list of pricing locations with optional filtering by ISOs, zones,\nzone types and a search term.\n\nArgs:\n params: Query parameters for filtering pricing locations\n sort_column: Column to sort by.\n sort_order: Sort order - 'asc' or 'desc'.","operationId":"list_pricing_locations_v1_pricing_locations_get","parameters":[{"name":"sort_column","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort Column"}},{"name":"sort_order","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/OrderBy"},{"type":"null"}],"title":"Sort Order"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional search term to filter locations by name","title":"Search"},"description":"Optional search term to filter locations by name"},{"name":"isos","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated list of market IDs to filter by","title":"Isos"},"description":"Comma-separated list of market IDs to filter by"},{"name":"zones","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated list of zones to filter by","title":"Zones"},"description":"Comma-separated list of zones to filter by"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated list of statuses to filter by","title":"Status"},"description":"Comma-separated list of statuses to filter by"},{"name":"location_types","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated list of location types to filter by","title":"Location Types"},"description":"Comma-separated list of location types to filter by"},{"name":"has_geo_data","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by whether locations have geographic data","title":"Has Geo Data"},"description":"Filter by whether locations have geographic data"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetedSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"OrderBy":{"type":"string","enum":["asc","desc"],"title":"OrderBy"},"FacetedSearchResponse":{"properties":{"items":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Items"},"total_items":{"type":"integer","title":"Total Items"},"facets":{"additionalProperties":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"type":"object","title":"Facets"}},"type":"object","required":["items","total_items","facets"],"title":"FacetedSearchResponse","description":"Response from get_items_and_facets containing items, total count, and facets."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## List Nearby Pricing Locations > Get a list of pricing locations near the provided latitude/longitude\ > or gs\_entity\_id. User must provide either latitude and longitude or a\ > gs\_entity\_id, but not both. ```json {"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/pricing_locations/nearby":{"get":{"tags":["Pricing Locations"],"summary":"List Nearby Pricing Locations","description":"Get a list of pricing locations near the provided latitude/longitude\nor gs_entity_id. User must provide either latitude and longitude or a\ngs_entity_id, but not both.","operationId":"list_nearby_pricing_locations_v1_pricing_locations_nearby_get","parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"latitude","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":90,"minimum":-90},{"type":"null"}],"description":"The latitude of the location to search","title":"Latitude"},"description":"The latitude of the location to search"},{"name":"longitude","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":180,"minimum":-180},{"type":"null"}],"description":"The longitude of the location to search","title":"Longitude"},"description":"The longitude of the location to search"},{"name":"gs_entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The GS entity ID of the location to search","title":"Gs Entity Id"},"description":"The GS entity ID of the location to search"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NearbyPricingLocationItem"},"title":"Response List Nearby Pricing Locations V1 Pricing Locations Nearby Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"NearbyPricingLocationItem":{"properties":{"gs_entity_id":{"type":"string","title":"Gs Entity Id"},"location":{"type":"string","title":"Location"},"market_id":{"type":"string","title":"Market Id"},"distance_in_miles":{"type":"number","title":"Distance In Miles"}},"type":"object","required":["gs_entity_id","location","market_id","distance_in_miles"],"title":"NearbyPricingLocationItem"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Get Pricing Location > Get data for a specific pricing location by its ID. ```json {"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/pricing_locations/{gs_entity_id}":{"get":{"tags":["Pricing Locations"],"summary":"Get Pricing Location","description":"Get data for a specific pricing location by its ID.","operationId":"get_pricing_location_v1_pricing_locations__gs_entity_id__get","parameters":[{"name":"gs_entity_id","in":"path","required":true,"schema":{"type":"string","title":"Pricing Location","description":"Name of the pricing location to query"},"description":"Name of the pricing location to query"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingLocationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"PricingLocationResponse":{"properties":{"gs_entity_id":{"type":"string","title":"Gs Entity Id"},"location":{"type":"string","title":"Location"},"location_type":{"type":"string","title":"Location Type"},"market_id":{"type":"string","title":"Market Id"},"baa":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Baa"},"zone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zone"},"zone_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zone Type"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"pricing_datasets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Pricing Datasets"},"earliest_seen_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Earliest Seen Utc"},"latest_seen_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Latest Seen Utc"},"status_threshold_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Threshold Days"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},"type":"object","required":["gs_entity_id","location","location_type","market_id","baa","zone","zone_type","latitude","longitude","earliest_seen_utc","latest_seen_utc","status_threshold_days","status"],"title":"PricingLocationResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.gridstatus.io/developers/api-reference/pricing-locations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.