Matomo

Matomo User Country API

The UserCountry API lets you access reports about your visitors' Countries and Continents.

GitHub OpenAPI
Business capability
Digital Marketing Management BC-400.60

Operations 8

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /index.php?module=API&method=UserCountry.getCountry Report visits by country · User country get country #
Ask an LLM
“Which countries do most of my visitors come from?”
“Can I see visits per country for a segment like mobile users?”
Tell an agent
Show visits by country for site {idSite} for {period} {date}.
Break down visitor countries for site {idSite} on {date} limited to segment {segment}.
GET /index.php?module=API&method=UserCountry.getContinent Report visits by continent · User country get continent #
Ask an LLM
“How is my traffic split between Europe, Asia and the Americas?”
“What share of visits come from each continent?”
Tell an agent
Show visits by continent for site {idSite} for {period} {date}.
Summarize continental traffic for site {idSite} on {date}.
GET /index.php?module=API&method=UserCountry.getRegion Report visits by region · User country get region #
Ask an LLM
“Which states or provinces send me the most visitors?”
“Can I see traffic broken down by region within countries?”
Tell an agent
Show visits by region for site {idSite} for {period} {date}.
List the states and provinces visitors came from on site {idSite} on {date}.
GET /index.php?module=API&method=UserCountry.getCity Report visits by city · User country get city #
Ask an LLM
“Which cities are my visitors located in?”
“What are the top cities for traffic last week?”
Tell an agent
Show visits by city for site {idSite} for {period} {date}.
Rank visitor cities for site {idSite} on {date}.
GET /index.php?module=API&method=UserCountry.getCountryCodeMapping Map ISO country codes to country names · User country get country code mapping #
Ask an LLM
“Can I get a lookup of ISO country codes to translated country names?”
“What country name does a two-letter code like 'de' map to?”
Tell an agent
Get the ISO country code to country name mapping.
Give me the list of country codes with their translated names.
GET /index.php?module=API&method=UserCountry.getLocationFromIP Geolocate an IP address · User country get location from IP #
Ask an LLM
“Where in the world is a particular IP address located?”
“Can I test geolocation for an IP using a specific location provider?”
Tell an agent
Look up the location of IP {ip}.
Geolocate IP {ip} using location provider {provider}.
GET /index.php?module=API&method=UserCountry.setLocationProvider Set the active geolocation provider · User country set location provider #
Ask an LLM
“How do I switch which geolocation provider is used for visitor locations?”
“Can I make a GeoIP database the active location provider?”
Tell an agent
Set the active geolocation provider to {providerId}.
Switch visitor geolocation to use provider {providerId}.
GET /index.php?module=API&method=UserCountry.getNumberOfDistinctCountries Count distinct visitor countries in a period · User country get number of distinct countries #
Ask an LLM
“How many different countries did visitors come from this month?”
“Can I get just the number of unique countries for a period?”
Tell an agent
Count the distinct countries for site {idSite} for {period} {date}.
Tell me how many unique countries visited site {idSite} on {date}.

Documentation

📖
Documentation
https://developer.matomo.org/api-reference/reporting-api
📖
Documentation
https://developer.matomo.org/api-reference/reporting-api#Live
📖
Documentation
https://developer.matomo.org/api-reference/reporting-api#Goals
📖
Documentation
https://developer.matomo.org/api-reference/reporting-api-segmentation

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/matomo/refs/heads/main/openapi/matomo-usercountry-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/matomo:matomo-usercountry-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

matomo-usercountry-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Matomo Reporting API for plugin User Country API
  version: 1.0.0
  description: The UserCountry API lets you access reports about your visitors' Countries and Continents.
servers:
- url: https://demo-proxy.innocraft.cloud/
  description: Current Matomo instance
security:
- MatomoToken: []
tags:
- name: UserCountry
  description: The UserCountry API lets you access reports about your visitors' Countries and Continents.
paths:
  /index.php?module=API&method=UserCountry.getCountry:
    get:
      tags:
      - UserCountry
      description: Returns visit information grouped by country.
      operationId: UserCountry.getCountry
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'Country rows with translated labels and flag metadata.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: User country get country
      x-summary-source: derived
  /index.php?module=API&method=UserCountry.getContinent:
    get:
      tags:
      - UserCountry
      description: Returns visit information grouped by continent.
      operationId: UserCountry.getContinent
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'Continent rows with translated labels and continent codes.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: User country get continent
      x-summary-source: derived
  /index.php?module=API&method=UserCountry.getRegion:
    get:
      tags:
      - UserCountry
      description: Returns visit information for every region with at least one visit.
      operationId: UserCountry.getRegion
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'Region rows with country, region, and flag metadata.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: User country get region
      x-summary-source: derived
  /index.php?module=API&method=UserCountry.getCity:
    get:
      tags:
      - UserCountry
      description: Returns visit information for every city with at least one visit.
      operationId: UserCountry.getCity
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'City rows with city, region, country, and flag metadata.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: User country get city
      x-summary-source: derived
  /index.php?module=API&method=UserCountry.getCountryCodeMapping:
    get:
      tags:
      - UserCountry
      description: Returns a mapping from ISO country code to translated country name.
      operationId: UserCountry.getCountryCodeMapping
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      responses:
        '200':
          description: 'Country names keyed by lowercase ISO country code.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: User country get country code mapping
      x-summary-source: derived
  /index.php?module=API&method=UserCountry.getLocationFromIP:
    get:
      tags:
      - UserCountry
      description: Uses a location provider to find/guess the location of an IP address.
      operationId: UserCountry.getLocationFromIP
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: ip
        in: query
        description: The IP address to geolocate, or `false` to use the current request IP.
        required: false
        schema:
          type: string
      - name: provider
        in: query
        description: The provider ID to use, or `false` to use the currently configured provider.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'Location data returned by the selected provider.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: User country get location from IP
      x-summary-source: derived
  /index.php?module=API&method=UserCountry.setLocationProvider:
    get:
      tags:
      - UserCountry
      description: Sets the active geolocation provider.
      operationId: UserCountry.setLocationProvider
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: providerId
        in: query
        description: The provider ID to activate, for example `default` or `geoip2_php`.
        required: true
        schema:
          type: string
          example: google
      responses:
        '200':
          $ref: '#/components/responses/GenericSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: User country set location provider
      x-summary-source: derived
  /index.php?module=API&method=UserCountry.getNumberOfDistinctCountries:
    get:
      tags:
      - UserCountry
      description: Returns the number of distinct countries in the requested period.
      operationId: UserCountry.getNumberOfDistinctCountries
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'Numeric archive result containing the number of distinct countries.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: User country get number of distinct countries
      x-summary-source: derived
components:
  responses:
    Forbidden:
      description: Authenticated but not allowed to access the resource.
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: Not authorised.'
        text/html:
          schema:
            type: string
          example: Not authorised.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
    BadRequest:
      description: Bad request (validation or missing parameters).
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: There was an error.'
        text/html:
          schema:
            type: string
          example: There was an error.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
    GenericSuccess:
      description: Generic 200 response
      content:
        text/plain:
          schema:
            type: string
          example: Success:ok
        text/html:
          schema:
            type: string
          example: '<!-- Success: ok -->'
        application/json:
          schema:
            $ref: '#/components/schemas/GenericSuccess'
        application/xml:
          schema:
            $ref: '#/components/schemas/GenericSuccessXml'
    NotFound:
      description: Resource not found.
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: The method is not available.'
        text/html:
          schema:
            type: string
          example: The method is not available.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
    Unauthorized:
      description: Authentication failed or missing token.
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: You must be logged in to access this functionality.'
        text/html:
          schema:
            type: string
          example: You must be logged in to access this functionality.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
    ServerError:
      description: Unexpected server error.
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: There was an error.'
        text/html:
          schema:
            type: string
          example: There was an error.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
    DefaultError:
      description: Default error response (any non-2xx).
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: There was an error.'
        text/html:
          schema:
            type: string
          example: There was an error.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
  schemas:
    ErrorXml:
      description: Generic Matomo error payload in XML.
      properties:
        error:
          properties:
            message:
              type: string
              xml:
                attribute: true
              example: There was an error
          type: object
          xml:
            name: error
      type: object
      xml:
        name: result
    Error:
      description: Generic Matomo error payload.
      required:
      - result
      - message
      properties:
        result:
          type: string
          example: error
        message:
          type: string
          example: There was an error
        code:
          type: integer
      type: object
      additionalProperties: true
    GenericSuccess:
      description: Generic Matomo success payload.
      required:
      - result
      - message
      properties:
        result:
          type: string
          example: success
        message:
          type: string
          example: ok
        code:
          type: integer
          example: '200'
      type: object
      example:
        result: success
        message: ok
      additionalProperties: true
    GenericSuccessXml:
      description: Generic Matomo success payload in XML.
      required:
      - success
      properties:
        success:
          properties:
            message:
              type: string
              xml:
                attribute: true
              example: ok
          type: object
          xml:
            name: success
      type: object
      xml:
        name: result
      example:
        success:
          message: ok
      additionalProperties: true
  parameters:
    formatOptional:
      name: format
      in: query
      description: Response format. Defaults to `xml`. Use `original` to get the original PHP data structure.
      required: false
      schema:
        type: string
        default: xml
        enum:
        - xml
        - json
        - csv
        - tsv
        - html
        - rss
        - original
  securitySchemes:
    MatomoToken:
      type: http
      description: Paste your token generated from Personal > Security. Swagger will send it as a Bearer token.
      scheme: bearer
externalDocs:
  description: Matomo Reporting API developer page
  url: https://developer.matomo.org/api-reference/reporting-api/