SmartNews

SmartNews Locations API

The locations API from SmartNews — 1 operation(s) for locations.

GitHub OpenAPI

Operations 1

GET /api/ma/v3/locations List Locations #

Documentation

📖
Documentation
https://ads.smartnews.com/developers/
📖
APIReference
https://ads.smartnews.com/developers/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/smartnews/refs/heads/main/openapi/smartnews-locations-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/smartnews-locations-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

smartnews-locations-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  version: 3.0.1
  title: SmartNews Marketing Locations API
  description: '# Previous Versions

    - SmartNews Marketing API (2.0.0): https://ads.smartnews.com/developers/deprecated/v2/index.html

    - **API v2 has been fully disabled.** All requests to `api/ma/v2/*` endpoints now return a `410 Gone` error.'
  contact:
    name: SmartNews Ads Support
servers:
- url: https://ads.smartnews.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Locations
paths:
  /api/ma/v3/locations:
    get:
      tags:
      - Locations
      summary: List Locations
      operationId: getLocations
      parameters:
      - name: region
        in: query
        required: false
        description: 'The region to obtain locations for.


          There are currently two regions: `JP` and `US`.

          - `JP`: contains all the prefectures and their cities in Japan.

          - `US`: contains all the states and their counties in the US.


          If a value is not specified, the default is `JP`.

          '
        schema:
          $ref: '#/components/schemas/Region'
      description: 'Returns an array of locations for the specified region (prefectures for `JP`, states for `US`).


        Each location contains an array of `children` objects, representing cities inside that prefecture for `JP`, and counties inside that state for `US`.


        Display names are provided in Japanese and English via the `ja` and `en` fields.'
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Locations'
              examples:
                japan:
                  value:
                  - location_id: 70149
                    ja: 北海道
                    en: Hokkaido
                    children:
                    - location_id: 70196
                      ja: 札幌市
                      en: Sapporo
                    - location_id: 70197
                      ja: 函館市
                      en: Hakodate
                  summary: A sample of the JP Locations.
                us:
                  value:
                  - location_id: 2
                    en: Washington
                    ja: Washington
                    children:
                    - location_id: 3
                      en: Pierce County
                      ja: Pierce County
                    - location_id: 76
                      en: Skagit County
                      ja: Skagit County
                  summary: A sample of the US Locations. Note that the "ja" names are not translated.
        '401':
          description: Unauthorized. The access token is either expired or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
              x-examples:
                expiredToken:
                  summary: Access token has expired.
                  value:
                    error:
                      type: UNAUTHORIZED
                      message: Token has expired.
                      retriable: false
                invalidToken:
                  summary: Access token is invalid.
                  value:
                    error:
                      type: UNAUTHORIZED
                      message: Token is invalid.
                      retriable: false
        '403':
          description: Forbidden. Access to the requested resource is denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
              examples:
                terms_of_service_not_accepted:
                  summary: User has not accepted the terms of service.
                  value:
                    error:
                      type: TERMS_OF_SERVICE_NOT_ACCEPTED
                      message: The owner of the assets must accept the Ads terms of service.
                      terms_of_service_path: /terms/agreement
                      retriable: false
                access_denied:
                  summary: Access is denied due to insufficient permissions.
                  value:
                    error:
                      type: ACCESS_DENIED
                      message: Access denied.
                      retriable: false
        '429':
          description: Too many requests were made within a short period. Wait a while and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedErrorResponse'
        '500':
          description: Unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnexpectedErrorResponse'
        '503':
          description: The service is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableErrorResponse'
components:
  schemas:
    UnauthorizedError:
      type: object
      allOf:
      - $ref: '#/components/schemas/UnauthorizedErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
    UnexpectedErrorExtension:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - UNEXPECTED_ERROR
    UnexpectedErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/UnexpectedError'
    UnexpectedError:
      type: object
      allOf:
      - $ref: '#/components/schemas/UnexpectedErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
    Locations:
      type: object
      required:
      - location_id
      - ja
      - en
      - children
      properties:
        location_id:
          $ref: '#/components/schemas/CommonSchemas_LocationId'
        ja:
          $ref: '#/components/schemas/LocationNameJapanese'
        en:
          $ref: '#/components/schemas/LocationNameEnglish'
        children:
          type: array
          description: 'An array of locations which are geographically contained within this location.

            '
          items:
            $ref: '#/components/schemas/LocationNameData'
    ServiceUnavailableErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ServiceUnavailableError'
    LocationNameJapanese:
      type: string
      example: 北海道
      description: The name of the location in Japanese.
    CommonSchemas_LocationId:
      type: integer
      format: int32
      example: 70149
      description: The location ID which can be used for AdGroup level location targeting.
    ServiceUnavailableErrorExtension:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - UNDER_MAINTENANCE
    ServiceUnavailableError:
      type: object
      allOf:
      - $ref: '#/components/schemas/ServiceUnavailableErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
    ForbiddenErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ForbiddenError'
    Region:
      type: string
      enum:
      - JP
      - US
      x-enum-varnames:
      - JP
      - US
    RateLimitedError:
      type: object
      allOf:
      - $ref: '#/components/schemas/ErrorBase'
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - TOO_MANY_REQUESTS
    LocationNameEnglish:
      type: string
      example: Hokkaido
      description: The name of the location in English.
    UnauthorizedErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/UnauthorizedError'
    RateLimitedErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/RateLimitedError'
    ErrorBase:
      type: object
      required:
      - message
      - retriable
      properties:
        message:
          type: string
        retriable:
          type: boolean
    UnauthorizedErrorExtension:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - UNAUTHORIZED
    LocationNameData:
      type: object
      required:
      - location_id
      - ja
      - en
      properties:
        location_id:
          $ref: '#/components/schemas/CommonSchemas_LocationId'
        ja:
          $ref: '#/components/schemas/LocationNameJapanese'
        en:
          $ref: '#/components/schemas/LocationNameEnglish'
    ForbiddenError:
      type: object
      allOf:
      - $ref: '#/components/schemas/ForbiddenErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
    ForbiddenErrorExtension:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - TERMS_OF_SERVICE_NOT_ACCEPTED
          - ACCESS_DENIED
        terms_of_service_path:
          type: string
          example: /terms/agreement
          description: The path that the user must open in a browser to accept the terms of service. The hostname matches the API hostname.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT