MNE Interface Needs some Major Work guys..

[slecrenski]

The interface for MPE is extremely non-intuitive and exceptionally difficult to work with. Literally the only way to know which direction of investment goes with which classification is to try each one and see which one fails then compile a list of acceptable reference data. Also the API requires classification but every time you call the API it says "Parameter classification not allowed in current query and will be dropped by API. Yet it returns data.. Also You have an additional space in the get_parameter_values for classification. It says "Classification " notice the space. This API needs to be simplified. Also it doesn't seem to have any data for many of the MPE endpoints for current years. Is MPE deprecated? Seems exceptionally important with Tariffs and such nowadays.

The following are the only mappings of direction of investment and classification that actually work.

{
    "inward": [
        "Country",
        "CountrybyType",
        "CountryofUBO",
        "CountryofUBObyIndustry",
        "countryofUBObyType",
        "Industry",
        "IndustrybyType",
        "StatebyType",
        "TypeofExpenditure"
    ],
    "outward": [
        "Country",
        "Industry"
    ],
    "parent": [
        "Country",
        "CountryofUBO",
        "IndustryofSales"
    ]
}

Yet there 4 types of directions and many types of classifications. These are the only ones which do not fail for ALL year which are the required fields.

Please let me know the correct way of using this API to extract all MPE data that is available. Thanks!

[slecrenski]

case 'MNE':
        direction_of_investment = beaapi.get_parameter_values(beakey, f'{dataset_key}', 'DirectionOfInvestment')
        print(direction_of_investment)
        for d_key, d_itm in direction_of_investment.values:
          #print(d_key)
          #bea_tbl = beaapi.get_data(beakey, datasetname=f'{dataset_key}', DirectionOfInvestment=f'{d_key}', Classification='Country', Year='ALL')
          #print(bea_tbl)
          classification = beaapi.get_parameter_values(beakey, f'{dataset_key}', 'Classification')
          #print(classification)
          for c_key, c_itm in classification.values:
            print(d_key, c_key)
            has_exception = False
            try:
              bea_tbl = beaapi.get_data(beakey, datasetname=f'{dataset_key}', DirectionOfInvestment=f'{d_key}', Classification=f'{c_key}', Year='ALL')
              if not d_key in mne_reference:
                mne_reference[d_key] = []
              mne_reference[d_key].append(c_key)
              print(json.dumps(mne_reference, indent=4, default=str))
            except Exception as e:
              has_exception = True
            print(d_key, c_key, has_exception)

[slecrenski]

the "state" direction of investment does not work at all. unless its timing out with year set to ALL

[slecrenski]

is there some way to increase timeout?

[slecrenski]

I tried it again with just 2023 and received the following

{
    "inward": [
        "Country",
        "CountryByIndustry",
        "CountrybyType",
        "CountryofUBO",
        "CountryofUBObyIndustry",
        "countryofUBObyType",
        "Industry",
        "IndustrybyType",
        "StatebyCountryofUBO",
        "StatebyType",
        "TypeofExpenditure"
    ],
    "outward": [
        "Country",
        "CountryByIndustry",
        "Industry",
        "StatebyCountryofUBO"
    ],
    "parent": [
        "Country",
        "CountryByIndustry",
        "CountryofUBO",
        "CountryofUBObyIndustry",
        "Industry",
        "IndustryofSales",
        "StatebyCountryofUBO"
    ]
}

[slecrenski]

"state" does absolutely nothing for any classification. If classification is not specified in the get_data statement everything fails. What am I missing? It's not me.

----------------------------------MNE---------------------------------------
            ParameterName ParameterDataType                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ParameterDescription  ParameterIsRequiredFlag ParameterDefaultValue  MultipleAcceptedFlag AllValue
0   DirectionOfInvestment            string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Four Possible Values:  (inward,outward,parent,state)                        1                                           0     <NA>
1          OwnershipLevel           integer                                                                                                                                                                                                                                                                                                                                    A value of 1 returns data for all affiliates.  A value of 0 returns data for majority-owned affiliates only.  Note that if directionOfInvestment = 'parent', then OwnershipLevel must be set to 1.                        0                     2                     0     <NA>
2   NonbankAffiliatesOnly           integer                                                                                                                                                                                                                                                                                                                 A value of 1 returns data for nonbank affiliates only.  A value of 0 returns data for both bank and nonbank affiliates.  A value of 0 is required for data for 2007 forward (for FDIUS) for 2009 forward (for USDIA).                        0                     2                     0     <NA>
3         Classification             string                                                                                                                                                                                                                                                                                                                                                          Classification is a string used to obtain data that is broken down by both country and industry for either inward or outward data.  It can take one of four possible values:                        1                  <NA>                     0     <NA>
4                 Country            string  Country is usually a number.  Because there can be several variants of a country's name, three-digit numeric codes are used to select countries.  A full list of these codes is available near the end of this document or can be obtained by using the GETPARAMETERVALUES method.  To obtain data for every country (including the all-country total) separately use 'all'.  To obtain a total for all countries, use '0000'.   To obtain data for multiple countries, each country code should be listed and separated by a comma.                        0                  <NA>                     1      all
5                Industry            string                                                                                                                                                                                                                                                                                                                          Industries are denoted by four-digit codes.  With a few exceptions, these codes follow the NAICS. To obtain data for every industry separately use 'all'.  To obtain a total for all industries, use '0000'.                        0                  <NA>                     1      all
6                    Year           integer                                                                                                                                                                                                                                                                                                                                                                  Year is a 4-digit numeric variable.  To obtain data for multiple years, each year should be listed and separated by a comma. To obtain data for all years use 'all'.                        1                                           1      all
7                   State            string                                                                                                                                                                                                 State specifies the U.S. state or states for data on foreign direct investment in the United States.  The state is specified by using the two-digit FIPS code.  For "Other U.S. areas", use code '70'.  For "Foreign", use code '75'.  To obtain data for all states and areas use 'all'.  To obtain a total U.S. figure, use '90'.                          0                  <NA>                     1      all
8                SeriesID            string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Series IDs                        0                   all                     1      all
9            GetFootnotes            string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Footnotes for the datavalues                        0                    no                     0     <NA>
10             Investment            string                                                                                                                                                                                                                                                                                                                                                                            Investments are denoted by Three-digit codes. To obtain data for every investment separately use 'all'.  To obtain a total for all investments, use '000'.                        0                  <NA>                     1      all
11       ParentInvestment            string                                                                                                                                                                                                                                                                                                                                                                            Investments are denoted by Three-digit codes. To obtain data for every investment separately use 'all'.  To obtain a total for all investments, use '000'.                        0                  <NA>                     1      all

       key                                                                                                                                                                                                                    desc
0   inward                                                  Provides data for U.S. affiliates of foreign multinational companies.  Note that for state-level data on U.S. affiliates, directionOfInvestment should be â.
1  outward                                                                                                                                                   Provides data for foreign affiliates of U.S. multinational companies.
2   parent                                                                                                                                                                                 Provides data on U.S. parent companies.
3    state  Provides data for U.S. affiliates of foreign multinational companies at the state level.  Note that only data on employment and (prior to 2007) gross property, plant, and equipment are available at the state level.

[bquistorff-bea]

Hi, yes these statistics are more irregular than some others, and so understanding what can be pulled, and how, can be more challenging. Aside from the general API documentation, you can also try to find the data you want first in iTables and then translate that to an API query. The iTables interface might be easier for exploring and we provide a rough guide to translating iTables queries to the API for MNE and it has some of the "what's allowed" information you were wanting. Though note, there are cases where data is available only through iTables and not the API.

As for empty results, sometimes this happens when a query takes too long. In general, narrowing the range of values requested can help. I'll see if I can find more information for your current query.

[bquistorff-bea]

We should have a fix incoming for the space issue.

[slecrenski]

Thanks. I’m using the API to extract all available data in BEA. It seems odd to me that I need specialized business logic in the usage of the API to extract data. I think it could arguably be greatly simplified in some way. I can also query all data from iTables but then this seems redundant.

[bquistorff-bea]

I'm copying here a response from someone on the MNE team about pulling the state data

---

In response to the user’s questions related to data by State, note that there are only a few International series that have data broken down by U.S. state, and only a subset of those are available from the API.

1. For Activities of Multinational Enterprises data, we only compile state data for number counts, employment, manufacturing employment, and gross property, plant and equipment. The complete data are in the static excel files. Some of these data items are in itables.

For the API, we only have employment by state and country of UBO and manufacturing employment by state and country of UBO. To get employment by state and country of UBO for majority-owned affiliates use:

beaapi.get_data(beakey, datasetname='MNE', DirectionOfInvestment='State', Classification='StatebyCountryofUBO', SeriesID='8', Year='All', getfootnotes='yes', Ownershiplevel='0', NonbankAffiliatesOnly='0')

Can also use ownershiplevel='1' for all affiliates

For manufacturing employment use SeriesID='9', only works with ownershiplevel='0'.

2. For New Foreign Direct Investment in the United States, data by state are available for investment values, employment and other activities data.

For total investment use seriesID 62:

beaapi.get_data(beakey, datasetname='MNE', DirectionOfInvestment='inward', Classification='StatebyType', SeriesID='62', Year='2020', getfootnotes='yes')

For other data on new foreign direct investment in the U.S. by state substitute seriesID 64, 66, 68, or 69.