Bitvore Economic News API

openapi: 3.2.0
info:
  description: '## Precision News API


    The Precision News APIs provide access to curated news annotated with metadata tags.'
  version: '1.0'
  title: Bitvore Legacy Economic News API
  license:
    name: Copyright Bitvore Corp. 2026
servers:
- url: https://api.bitvore.com/
tags:
- name: Economic News
  description: Economic News API
paths:
  /econnews:
    get:
      tags:
      - Economic News
      summary: Economic News Query
      description: 'Provides the ability to search for news relevant to economy of a location or region:

        * State - Querying by state returns only news articles that have been written about events that have occurred within the given state.

        * City - Querying by city returns only news articles that have been written about events that have occurred within the given city. This option requires the use of the State option to avoid ambiguity.

        * FIPS - Querying by FIPS code returns only news articles that have been written about events that have occurred within the given county or CBSA. FIPS codes for counties can be found here. FIPS codes for CBSAs can be found here. Maps of CBSAs can be found here.

        * Free Form Text Search - A search for words or phrases can be performed against the articles matching any of the previous options listed.

        * Significance - Articles are classified by their significance. A highly significant article is one that is alert worthy whereas less significant articles are more relevant when performing research. This option will filter the results returned by the previous options listed.

        can affect performance. In order to guarantee our SLA the number of articles returned will be reduced.


        The following is an example of using the API.


        To query for the economic news about Irvine, California between 7/1/2018 and 7/31/2018 :


        ```js

        GET /econnews?state=ca&city=irvine&startDate=2018-07-01&endDate=2018-07-31&tz=PST HTTP 1.1

        Accept: application/json

        X-BV-APIKEY: xyz123...

        ```


        A sample successful response is:


        ```js

        {

        "success": true,

        "returned": 1,

        "total": 1,

        "response": [

        {

        "key": "070000015cf083aba01f0826ecfe718e965b577c572166b14a77651c",

        "articleType": "News",

        "title": "Irvine And Carlsbad Water Agreement",

        "sourceName": "dailyexpress.com",

        "sourceUrl": "http://ct.moreover.com/?a=41646891667&p=5jw&v=1&x=yg6DsqTFf8IC8ym026-o0A",

        "previewImageUrl": "http://dailyexpress.com/resources/irvine-carlsbad.jpg",

        "excerpt": "Irvine has agreed to buy water from the City of Carlsbad. The Carlsbad desalination ...",

        "locations": ["/Orange County/California/United States", "Los Angeles//California/United States"],

        "sentiment" : 0.28571313,

        "significance": "HIGH",

        "publishedAt": "2017-06-29T21:41:19.109Z",

        "availableAt": "2017-06-29T21:41:21.109Z",

        }

        ]

        }

        ```

        A sample unsuccessful response is:


        ```js

        {

        "success": false,

        "reason": "Invalid state specified",

        "reasonSupport": "san irvine",

        "count": 0

        }

        ```'
      operationId: handleEconSearchUsingGET
      parameters:
      - name: state
        in: query
        description: State to retrieve municipal and economic news for. Must not be used with the cusip or portfolio parameters.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: city
        in: query
        description: City to retrieve municipal and economic news for, must be used with the state parameter and not with the cusip or portfolio parameters.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: fips
        in: query
        description: FIPS code to retrieve municipal and economic news for. Must not be used with the cusip or portfolio parameters.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: text
        in: query
        description: Keyword or phrase to search for news when not using a portfolio
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: startDate
        in: query
        description: News date to start from. Format is yyyy-mm-dd for daily news or yyyy-mm-dd'T'HH:mm if you want it down to the hour or minute. Should not be used if offset parameter is.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: endDate
        in: query
        description: News date to end with. Format is yyyy-mm-dd for daily (inclusive) news or yyyy-mm-dd'T'HH:mm if you want it down to the hour or minute. If startDate is used and endDate is not the default endDate is today.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: offset
        in: query
        description: Number of days back news should be returned for. Should not be used with startDate. Default is 31.
        required: false
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
      - name: tz
        in: query
        description: Timezone used in startDate and endDate.
        required: false
        allowEmptyValue: false
        schema:
          type: string
          default: GMT
      - name: dateType
        in: query
        description: Indicates whether dates to query by should be published dates "published" or available dates (processing completed) "available". Default is published.
        required: false
        allowEmptyValue: false
        schema:
          type: string
          default: published
      - name: pageNo
        in: query
        description: Page number of the total result set to return, default is 1.
        required: false
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
          default: 1
      - name: pageSize
        in: query
        description: Number of results out of the total result set per page to return, default is 100, maximum is 1000.
        required: false
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
          default: 100
      - name: significance
        in: query
        description: Significance of articles to return, possible values are "HIGH" and "MEDIUM", default is "HIGH". The parameter is a threshold so a value of MEDIUM will return MEDIUM and HIGH significance articles.
        required: false
        allowEmptyValue: false
        schema:
          type: string
          default: HIGH
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MuniNewsSearchResponseLegacy'
                originalRef: MuniNewsSearchResponseLegacy
        '401':
          description: Unauthorized to view intelligence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
      security:
      - API key:
        - Global
      - BasicAuth:
        - Global
      - OAuth:
        - Global
      deprecated: false
components:
  schemas:
    ReasonResponse:
      type: object
      properties:
        reason:
          type: string
          example: Could not locate subject.
          description: Text reason for the failure (if not successful)
        reasonSupport:
          type: object
          example: Longer description of the missing subject.
          description: Additional information about the failure (if not successful)
        response:
          type: object
          description: Response payload
        success:
          type: boolean
          example: true
          description: Indicates whether the call was successful or not
      title: ReasonResponse
      description: A response used to explain a failure or issue with the request.
    MuniNewsSearchResponseLegacy:
      type: object
      required:
      - returned
      - total
      properties:
        reason:
          type: string
          example: Could not locate subject.
          description: Text reason for the failure (if not successful)
        reasonSupport:
          type: string
          example: Longer description of the missing subject.
          description: Additional information about the failure (if not successful)
        response:
          type: array
          description: Response payload
          items:
            $ref: '#/components/schemas/MuniNewsArticleLegacy'
            originalRef: MuniNewsArticleLegacy
        returned:
          type: integer
          format: int32
          example: 10
          description: Number of news articles returned by search, maximum amount dictated by the pageSize parameter used in search
        success:
          type: boolean
          example: true
          description: Indicates whether the call was successful or not
        total:
          type: integer
          format: int32
          example: 100
          description: Total Number of news articles found by search
      title: MuniNewsSearchResponseLegacy
      description: Muni news search response.
    MuniNewsArticleLegacy:
      type: object
      properties:
        articleType:
          type: string
          example: PressRelease
          description: Type of article. Possible values are "News" and "PressRelease
        availableAt:
          type: string
          example: '2017-06-29T21:41:21.109Z'
          description: Date published
        cusips:
          type: array
          example: 02361DAP5, 002824AV2
          description: CUSIPs affected by the article. Required valid CUSIP license and permission.
          items:
            type: string
        excerpt:
          type: string
          example: ACME announces long awaited acquisition. The acquisition of Wile E. Coyote was announced Thursday.
          description: Fragment or snippet, of the article
        key:
          type: string
          example: 070000015cf083aba01f0826ecfe718e965b577c572166b14a77651c
          description: Key uniquely identifying the article
        locations:
          type: array
          example: Irvine//California/United States, /San Diego County/California/United States
          description: Locations affected. A location is city or county level. It is encoded as city/county/state/country where if the city is specified the county will not be and vice-versa
          items:
            type: string
        matchedCusips:
          type: array
          example: 02361DAP5, 002824AV2
          description: CUSIPs affected by the article that match the input CUSIPs, or are contained in the supplied portfolio.
          items:
            type: string
        previewImageUrl:
          type: string
          example: http://acme.com/resources/coyote.jpg
          description: URL of a preview image
        publishedAt:
          type: string
          example: '2017-06-29T21:41:21.109Z'
          description: Date available
        sectors:
          type: array
          example: Education, Utilities
          description: Sectors which the article belongs to.
          items:
            type: string
        sentiment:
          type: number
          format: double
          example: 0.23456
          description: Sentiment of the article. The value is a decimal value between -1 and 1, under 0 is negative while over 0 is positive.
        significance:
          type: string
          example: HIGH
          description: Significance of the article. Possible values are "HIGH" and "MEDIUM"
        sourceName:
          type: string
          example: businesswire.com, The Washington Daybook
          description: Name or host name of the publisher of the article
        sourceUrl:
          type: string
          example: http://acme.com/press
          description: URL to the original source of the article
        title:
          type: string
          example: ACME acquires Wile E. Coyote, Inc.
          description: Title
      title: MuniNewsArticleLegacy
      description: Muni news article.
  securitySchemes:
    API_key:
      type: apiKey
      name: X-BV-APIKEY
      in: header
    BasicAuth:
      type: http
      scheme: basic
    OAuth:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            Global: Includes all Bitvore APIs
          tokenUrl: https://api.bitvore.com/oauth/accesstoken