> For the complete documentation index, see [llms.txt](https://everyday-digital.gitbook.io/falkor-dev-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://everyday-digital.gitbook.io/falkor-dev-docs/analytics/audience/locations.md).

# Locations

The Locations endpoint allows viewing analytics on country locations from users that chosen to share their location. This end point allows location analytics to be viewed for Apps, Stories, Pathways OR Streams.  

This endpoint only provides locations at a country level and not down to specific cities.

## Available Frequency Endpoints

`v1/analytics/locations/apps`\
Get locations for an app or a list of apps.

`v1/analytics/locations/pathways`\
Get locations for a pathways or a list of pathways.

`v1/analytics/locations/streams`\
Get locations for a stream or a list of streams.

`v1/analytics/locations/stories`\
Get locations for a story or a list of stories.

## Parameters <a href="#parameters" id="parameters"></a>

The items parameter allows you to filter items based on the name or ID of the item. If the item parameter is not provided the endpoint will return the latest 10 items.

<table><thead><tr><th width="194"></th><th></th></tr></thead><tbody><tr><td><strong>Key</strong></td><td><strong>Value</strong></td></tr><tr><td><strong>items</strong></td><td><strong>Array of Strings</strong> <br>Item name or ID</td></tr></tbody></table>

## Examples

### Get Countries For Apps

The example below retrieves countries for a list of apps.

```
curl -X POST \
  v1/analytics/locations/apps \
  -H 'Authorization: Basic <Your Base64 Encoded Token>'\
```

### Get Countries For A Specific Pathway

The example below retrieves countries for a single pathway.

```
curl -X POST \
  v1/analytics/locations/pathways \
  -H 'Authorization: Basic <Your Base64 Encoded Token>'\
  -d '{
    "items" : ["My Pathway"]
  }'
```

## Success Response

Whichever `location` endpoint you are using a successful response will return an array of items with each item containing a context item (app, pathway, stream or story) and corresponding `locations` data. The example below shows a successful response when using the `location/apps` endpoint.

```
{
    "status": "success",
    "data": [
        {
      
            "app": {
                "name": "Falkor",
                "version": "2.10.1",
                "type": "app",
                "ID": "io.falkor.demo"
            },
            "locations": [
                {
                    "country": "South Africa",
                    "users": 10512
                },
                {
                    "country": "United Kingdom",
                    "users": 20456
                },
                ...etc
            ]
        },
        ...etc
    ],
    "hash": "53075327cebbf42738d0a0e38c77b8f3",
    "response_time": 0.184251070022583
}
```